Skip to content
Back to search

x12-mcp

MCP server that lets Claude parse, validate and explain X12 EDI files

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/harithatripuraneni-del--x12-mcp/badge.svg)](/listings/harithatripuraneni-del--x12-mcp)

HTML

<a href="/listings/harithatripuraneni-del--x12-mcp"><img src="/api/listings/harithatripuraneni-del--x12-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Python 3.10+.

git clone https://github.com/harithatripuraneni-del/x12-mcp.git
cd x12-mcp
pip install -e ".[dev]"
pytest

Connect it to Claude Code

claude mcp add x12 -- python -m x12_mcp.server

Connect it to Claude Desktop

Add this to `claude_desktop_config.json`:

{
  "mcpServers": {
    "x12": {
      "command": "python",
      "args": ["-m", "x12_mcp.server"]
    }
  }
}

Then try it with the files in [`samples/`](samples/): one valid 214 shipment status and one deliberately broken 204 load tender.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 102 lines
  1. # x12-mcp
  2. **Give Claude the ability to read, validate and explain X12 EDI.**
  3. X12 EDI still moves most of the world's freight, purchase orders and invoices, but AI assistants don't understand it out of the box. `x12-mcp` is a small [Model Context Protocol](https://modelcontextprotocol.io) server that teaches Claude (or any MCP client) to work with X12 files safely.
  4. Ask Claude things like:
  5. - *"Is this 204 valid? What's wrong with it?"*
  6. - *"Where is this shipment right now?"* (with a 214 pasted in)
  7. - *"What does the AT7 segment mean?"*
  8. ## Tools
  9. | Tool | What it does |
  10. | --- | --- |
  11. | `validate_edi` | Checks ISA/IEA, GS/GE and ST/SE control numbers and counts, segments outside envelopes, and required segments for 204, 210, 214, 990 and 997 |
  12. | `parse_edi` | Breaks a file into envelopes, transactions and segments, with delimiters read from the ISA header |
  13. | `summarize_shipment_status` | Turns a 214 into references, parties and a plain-English status timeline |
  14. | `explain_segment` | Explains what a segment ID is for |
  15. ## Design choices
  16. - **Read-only by design.** Every tool takes text and returns data. The server never opens files, calls the network or changes anything, and each tool is annotated as read-only for the client.
  17. - **Deterministic verdicts.** Pass or fail comes from plain, tested code, not from the model. Claude explains the results; it doesn't decide them.
  18. - **No assumptions about delimiters.** Separators are read from the ISA header, so files using `|`, `:` or newline terminators work too.
  19. - **Zero-dependency core.** The parser and validator are pure Python; only the server layer needs the MCP SDK.
  20. ## Quick start
  21. Requires Python 3.10+.
  22. ```bash
  23. git clone https://github.com/harithatripuraneni-del/x12-mcp.git
  24. cd x12-mcp
  25. pip install -e ".[dev]"
  26. pytest
  27. ```
  28. ### Connect it to Claude Code
  29. ```bash
  30. claude mcp add x12 -- python -m x12_mcp.server
  31. ```
  32. ### Connect it to Claude Desktop
  33. Add this to `claude_desktop_config.json`:
  34. ```json
  35. {
  36. "mcpServers": {
  37. "x12": {
  38. "command": "python",
  39. "args": ["-m", "x12_mcp.server"]
  40. }
  41. }
  42. }
  43. ```
  44. Then try it with the files in [`samples/`](samples/): one valid 214 shipment status and one deliberately broken 204 load tender.
  45. ## Example
  46. Validating `samples/load_tender_204_broken.edi` returns:
  47. ```json
  48. {
  49. "valid": false,
  50. "errors": [
  51. {"code": "SE_SEGMENT_COUNT", "message": "SE01 says 7 segments but the transaction has 6.", "position": 8},
  52. {"code": "SE_CONTROL_MISMATCH", "message": "SE02 '0002' does not match ST02 '0001'.", "position": 8},
  53. {"code": "IEA_CONTROL_MISMATCH", "message": "IEA02 '000000999' does not match ISA13 '000000202'.", "position": 10}
  54. ],
  55. "warnings": []
  56. }
  57. ```
  58. ## Project layout
  59. ```
  60. src/x12_mcp/
  61. parser.py read delimiters, split segments, build ISA/GS/ST envelopes
  62. validator.py deterministic envelope and structure checks
  63. dictionary.py reference data: segments, transaction sets, status codes
  64. explain.py plain-English summaries and a JSON outline
  65. server.py the MCP server and its four tools
  66. tests/ pytest suite
  67. samples/ synthetic example files (no real trading-partner data)
  68. ```
  69. ## Limitations and next steps
  70. This is a focused starting point, not a full X12 implementation. It does not validate element-level rules from implementation guides (lengths, code lists, loops). Ideas for what's next:
  71. - Summaries for 204 load tenders and 210 invoices
  72. - Generating a 997 acknowledgment from validation results
  73. - Loading partner-specific rules from a simple config file
  74. ## License
  75. MIT. Sample files are synthetic and contain no real company data.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.