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

Tool	What it does
parse_edi	Converts an EDI file to JSON, saves it to a file, and summarizes the interchanges and transaction sets
validate_edi	Validates an EDI file up to HIPAA SNIP level 4, and returns each error with the segment it is in
acknowledge_edi	Saves a 999 or 997 for an X12 file, with a TA1 when the interchange asks for one
build_edi	Converts EDI JSON to an EDI file
split_edi	Saves each transaction set in a file as its own EDI file
describe_spec	Describes a transaction set from the model the other tools use, standard or custom: its loops and segments with their JSON property names, or one segment's elements, types, lengths, codes and syntax rules. With output: skeleton, it makes JSON of the required parts to fill in for build_edi
get_status	Shows the license and how it's checked, where models come from and the allowed folders

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.

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 and open it. Claude Desktop installs it and asks for 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

Variable	What it does
EDIFABRIC_SERIAL	Your ediFabric serial. The default is the demo serial
EDIFABRIC_TOKEN	A token issued for you, for machines without internet access. See Licensing and quotas
EDIFABRIC_TOKEN_CACHE	The folder for cached tokens, or none to keep them in memory only. The default is your user cache folder
EDIFABRIC_ALLOWED_DIRS	The folders the tools can read and write, separated by ; on Windows and : elsewhere. Without it, the server uses the folders your MCP client shares, or your home folder
EDIFABRIC_MAP	A map.json with local or custom models. See Models
EDIFABRIC_OFFLINE	Set to true to use only the models in EDIFABRIC_MAP
EDIFABRIC_LIBRARY	The path to the ediFabric Native library, if it isn't the one installed with the package

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.

Plan	How it works
Community	Each tool call that reads or writes EDI is checked online and counts towards your quota, so the server needs internet access. It allows 250 operations a day; see pricing
Developer	The server gets a token for this machine and saves it, so operations are checked locally and a restart needs no license call. It refreshes the token by itself. The plan covers up to 3 machines
Enterprise, Perpetual	The same, with a token that isn't limited to one machine
Issued token	Set EDIFABRIC_TOKEN to a token issued for you, such as for a Perpetual license or a site without internet access. The server makes no license calls. Without EDIFABRIC_SERIAL as well, it can only use the models in EDIFABRIC_MAP

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 install
npm 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.