nacha-mcp

nacha-mcp

An MCP (Model Context Protocol) server for parsing and validating NACHA/ACH files.

Requirements

• Node.js 18 or later
• npm

Setup

git clone https://github.com/msuresh007/nacha-mcp.git
cd nacha-mcp
npm install
npm run build

This compiles src/ to dist/. Re-run npm run build after pulling any updates.

Try it out

A small, arithmetically-valid sample file is included at examples/sample.ach. Once built, you can run either tool directly from the command line without an MCP client, to confirm everything works:

node -e "const {analyzeNachaFile}=require('./dist/analyze.js');const fs=require('fs');console.log(JSON.stringify(analyzeNachaFile(fs.readFileSync('examples/sample.ach','utf-8')),null,2))"

You should see "valid": true with an empty issues array, one batch, and one entry.

Tools

• parse_nacha_file — Parses a NACHA file at a given path into full structured JSON: file header, batches (header, entries with addenda, control), and file control.
• summarize_nacha_file — Parses a NACHA file and returns a condensed summary: batch count, total entries, total debit/credit amounts, SEC codes present, and validation issues.

Both tools take a single input, file_path, an absolute path to the file on disk.

Parsing includes:

• Structural validation (record length, record type ordering, batch header/control pairing).
• Arithmetic validation — entry hash, debit/credit totals, and entry/addenda counts are recomputed from the actual entries and cross-checked against the declared Batch Control and File Control values. Mismatches are reported as validation issues rather than silently accepted.
• IAT (International ACH Transaction) batches and addenda type codes 10-18.

Running standalone

npm start

The server communicates over stdio using the MCP protocol; it's not meant to be run interactively on its own. Use it through an MCP client as described below.

Connect to Claude Code

From the project directory, after building:

claude mcp add nacha -- node "$(pwd)/dist/index.js"

(On Windows PowerShell: claude mcp add nacha -- node "$PWD\dist\index.js")

Connect to GitHub Copilot (VS Code)

Create .vscode/mcp.json in the project you want to use it from (or add to it if it already exists), replacing the path with the absolute path to your clone of this repo:

{
  "servers": {
    "nacha": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/nacha-mcp/dist/index.js"]
    }
  }
}

Alternatively, run MCP: Add Server from the Command Palette (Ctrl+Shift+P / ⇧⌘P), choose Workspace, and point it at node with the same args — VS Code writes the same .vscode/mcp.json for you.

Once saved, open Copilot Chat, switch to Agent mode, and the parse_nacha_file / summarize_nacha_file tools will be available (VS Code starts the server on demand).

Connect to Claude Desktop or another MCP client

Add an entry to the client's MCP server config (e.g. claude_desktop_config.json), replacing the path with the absolute path to your clone of this repo:

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

Restart the client after adding the config.

Project layout

• src/constants.ts — SEC codes, transaction codes, ISO country/currency lookups.
• src/format.ts — money/date/time field parsing.
• src/parser.ts — structural validation and record parsing (file/batch/entry/addenda).
• src/validate.ts — arithmetic validation (hashes, totals, counts).
• src/analyze.ts — combines parsing and arithmetic validation.
• src/summarize.ts — condensed summary view.
• src/index.ts — MCP server and tool registration.

No unit tests are included by design — this is meant to stay a small, easily auditable server.

License

MIT — see LICENSE.