ediFabric EDI

ediFabric MCP Server

An MCP server for EDI, currently X12 and HIPAA. It lets AI assistants such as Claude, Cursor and GitHub Copilot convert EDI to JSON and back, validate files, and generate 997 and 999 acknowledgments, using ediFabric Native on your own machine.

Your EDI files stay on your machine: the server reads and writes them locally, and returns summaries to the assistant rather than whole files.

Tools

The tools detect the format from the file, and take an optional format to set it.

Try asking:

• "Validate claims.837 at SNIP level 4 and explain each error."
• "Generate a 999 for every file in the inbound folder."
• "Convert po.edi to JSON, change the quantity on line 2 to 12, and build it back to X12."
• "What does an 856 in 004010 look like? Create a sample one."

Install

You need Node.js 18 or later. The server runs on Windows x64, Linux x64 and arm64, and macOS on Apple silicon.

Without EDIFABRIC_SERIAL, the server uses the free demo serial, which has a small daily quota and isn't for production. Use your own serial from Your account.

[Add to Cursor] [Install in VS Code] [Claude Desktop bundle]

Claude Code

Install it as a plugin, which asks for your serial and keeps it in your system's credential store:

/plugin marketplace add EdiFabric/edifabric-mcp/plugin install edifabric@edifabric

Or add the server on its own:

claude mcp add edifabric -e EDIFABRIC_SERIAL=YOUR_SERIAL -- npx -y @edifabric/mcp

On Windows, outside WSL, run npx through cmd: claude mcp add edifabric -e EDIFABRIC_SERIAL=YOUR_SERIAL -- cmd /c npx -y @edifabric/mcp.

Claude Desktop

Download edifabric-mcp-<version>.mcpb from the latest release, then open it in Claude Desktop in one of these ways:

• double-click the file (installing Claude Desktop registers the .mcpb file type);
• drag the file onto the Claude Desktop window;
• in Claude Desktop, go to Settings > Extensions > Advanced settings > Install Extension... and select the file.

Claude Desktop shows the extension: select Install, then enter your serial and your EDI folder. The bundle includes everything, so you don't need Node.js.

Or add this to claude_desktop_config.json, under Settings, Developer, Edit Config:

{  "mcpServers": {    "edifabric": {      "command": "npx",      "args": ["-y", "@edifabric/mcp"],      "env": {        "EDIFABRIC_SERIAL": "YOUR_SERIAL",        "EDIFABRIC_ALLOWED_DIRS": "C:\\EDI"      }    }  }}

Cursor

Add this to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json:

{  "mcpServers": {    "edifabric": {      "command": "npx",      "args": ["-y", "@edifabric/mcp"],      "env": { "EDIFABRIC_SERIAL": "YOUR_SERIAL" }    }  }}

VS Code

Add this to .vscode/mcp.json:

{  "servers": {    "edifabric": {      "type": "stdio",      "command": "npx",      "args": ["-y", "@edifabric/mcp"],      "env": { "EDIFABRIC_SERIAL": "YOUR_SERIAL" }    }  }}

OpenAI Codex

Add this to ~/.codex/config.toml:

[mcp_servers.edifabric]command = "npx"args = ["-y", "@edifabric/mcp"]env = { EDIFABRIC_SERIAL = "YOUR_SERIAL" }

Gemini CLI, Windsurf and others

Gemini CLI (~/.gemini/settings.json), Windsurf (~/.codeium/windsurf/mcp_config.json), Cline, and most other clients take the same mcpServers entry as Claude Desktop.

Other MCP clients use the same command, npx -y @edifabric/mcp, and the same environment variables.

Configuration

Models

Each transaction set is read and validated with a model for its type and version. By default, the server downloads the standard X12 and HIPAA models from EdiNation, which sends the transaction type and version, never the contents of your files.

To use local or custom models, such as ones you made in the EDI Spec Builder and downloaded for ediFabric Native, list them in a map.json and set EDIFABRIC_MAP to it:

{  "default": "",  "maps": {    "837:005010X222A1": { "type": 1, "name": "model837P.json", "location": "." },    "850:004010": { "type": 1, "name": "acme-850.json", "location": "models" }  }}

Each key is the transaction set and version from ST or GS. location is relative to the map file. Transactions that aren't in the map still use the online models, unless EDIFABRIC_OFFLINE is true.

describe_spec finds models the same way, so it describes your custom models too. It keeps the models it downloads in memory only, and never saves them.

Licensing and quotas

How the license is checked depends on your plan. You don't have to choose: set EDIFABRIC_SERIAL, and get_status shows which applies.

To upgrade, keep your serial if it stays the same, or set the new one in EDIFABRIC_SERIAL, and restart your MCP client. describe_spec and get_status don't read or write EDI, so they don't count as operations. describe_spec downloads models with your serial, as the other tools do.

This MCP server is open source under the MIT license. ediFabric Native, which it uses through the edifabric-x12 package for X12, is licensed under the ediFabric EULA.

Development

npm installnpm test

The tests need Node.js 22.9 or later, for --env-file-if-exists. They use the sample model in test/fixtures and need a serial with quota left. Put EDIFABRIC_SERIAL=YOUR_SERIAL in a .env.local file, which git ignores, or set the variable. They need ediFabric Native 120 or later: set EDIFABRIC_LIBRARY if the installed package has an older one. Set EDIFABRIC_ONLINE_TESTS=1 to include the tests that download models online. To try the server interactively, run npm run inspect.

Adding a format

Each EDI format has a module in src/formats, with its own ediFabric Native library and bindings package. To add one, such as EDIFACT with edifabric-edifact-tools, write a module with the same members as src/formats/x12/index.js and register it in src/formats/index.js. The tools, licensing and models then work with it. Its library loads only when a file of that format is used, so the bindings package can be an optional dependency. test/formats.test.js shows a complete example with a stand-in library.