edi-mcp

Let AI agents read, validate and acknowledge EDI documents.

An MCP (Model Context Protocol) server that parses raw X12 and EDIFACT interchanges into structured JSON, validates envelope integrity, produces plain-language summaries, and generates 997 Functional Acknowledgments. Zero runtime dependencies beyond the MCP SDK - the tokenizer is hand-rolled and reads delimiters from the wire, the way real-world files demand.

Works with Claude (Desktop, Code, API), Cursor, and any MCP-compatible client.

Why

EDI predates JSON by decades and still moves most B2B commerce: purchase orders (850/ORDERS), invoices (810/INVOIC), ship notices (856). None of it is reachable by no-code AI connectors - there is no REST API to point Zapier at, just structured text flowing over AS2/SFTP. This server gives an AI agent eyes on that traffic:

• "Summarize the PO that just landed in the inbox folder"
• "Does this 810 match the PO number and line totals we sent?"
• "Draft the 997 acknowledgment for this interchange"

Tools

Tool	What it does
parse_edi	Raw X12/EDIFACT (auto-detected) → structured JSON: envelope, groups, transactions, segments
validate_edi	Envelope integrity: control number agreement (ISA/IEA, GS/GE, ST/SE, UNB/UNZ, UNH/UNT) + declared counts
summarize_edi	Plain-language business summary. Deep support: X12 850/810/856, EDIFACT ORDERS/INVOIC. Other types get a segment inventory
generate_997_ack	X12 997 Functional Acknowledgment answering an interchange, sender/receiver swapped, AK2/AK5 per transaction

Quick start

git clone https://github.com/heocoi/edi-mcp.git
cd edi-mcp
npm install && npm run build

Claude Code:

claude mcp add edi -- node /path/to/edi-mcp/dist/index.js

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "edi": {
      "command": "node",
      "args": ["/path/to/edi-mcp/dist/index.js"]
    }
  }
}

Then try: "Parse samples/850-purchase-order.edi and tell me the PO number, ship-to address and order value."

Example

Input (X12 850, abbreviated):

ISA*00*...*ZZ*ACMECORP*ZZ*WIDGETSUPPLY*260719*1030*U*00401*000000101*0*P*>~
GS*PO*ACMECORP*WIDGETSUPPLY*20260719*1030*101*X*004010~
ST*850*0001~
BEG*00*SA*PO-2026-4521**20260719~
PO1*1*48*EA*9.75**VP*WS-4417*UP*012345678905~
...

summarize_edi output:

X12 interchange 000000101 - ACMECORP → WIDGETSUPPLY, dated 2026-07-19

## 850 Purchase Order (control 0001)
- Purchase Order PO-2026-4521 dated 2026-07-19 (type SA)
- Ship-to: Acme Corp Warehouse 7
- Line 1: 48 EA @ 9.75 - VP WS-4417, UP 012345678905
- Line 2: 12 CS @ 142.00 - VP WS-9902
- Computed order value: 2172.00
- CTT declares 2 line item(s)

Design notes

• Delimiters come from the wire, not from config. X12 delimiters are read from the ISA segment itself; EDIFACT service characters from UNA when present, standard defaults otherwise. EDIFACT release-character escaping (?+ → literal +) is honored.
• Lenient parse, strict validate. parse_edi recovers what it can and reports anomalies as warnings; validate_edi is the strict pass. Real-world EDI is messy - a parser that throws on the first oddity is useless for triage.
• Acknowledgment policy is explicit. decideAckStatus() in src/ack997.ts maps validation results to A/E/R. Default: clean → A, structural errors → R. Trading partner agreements differ; the policy is one small function on purpose.

Scope and roadmap

Current scope is read/triage/acknowledge - the 80% of daily EDI pain that needs no certification. Not yet included: 999 Implementation Acknowledgment, transaction-set-level schema validation (dictionaries per version), generating outbound 810/856, AS2 transport. Tracking the MCP 2026-07-28 spec revision.

Custom integrations

I build custom MCP servers for systems that no off-the-shelf connector covers: legacy ERPs, proprietary internal tools, SOAP/EDI/flat-file pipelines. If your business runs on a system your AI tools can't see, reach out: anhphong.pham@gmail.com · anhphong.dev

License

MIT