nacha-mcp

一个用于解析和验证 NACHA/ACH 文件的 MCP（模型上下文协议）服务器。

环境要求

• Node.js 18 或更高版本

• npm

Related MCP server: acmt001-mcp

安装

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

此操作会将 src/ 编译到 dist/。在拉取任何更新后，请重新运行 npm run build。

试用

examples/sample.ach 是一个算术上有效的小样例文件。构建完成后，你可以在没有 MCP 客户端的情况下，直接从命令行运行任一工具，以确认一切正常：

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))"

你应该会看到 "valid": true，同时 issues 数组为空，并且包括一个批次和一个条目。

工具

• parse_nacha_file — 解析给定路径的 NACHA 文件，输出完整的结构化 JSON 数据：文件头、批次（批头、带附加记录的条目、批控制）以及文件控制。

• summarize_nacha_file — 解析 NACHA 文件并返回简洁摘要：批次数、总条目数、借方/贷方总额、出现的 SEC 代码以及验证问题。

这两个工具都只接收一个输入参数 file_path，即文件在磁盘上的绝对路径。

解析包括：

• 结构验证（记录长度、记录类型顺序、批头/批控制配对）。

• 逻辑验证 — 根据实际条目重新计算条目哈希、借贷总额及条目/附加条目数量，并与所声称的批控制（Batch Control）和文件控制（File Control）值进行交叉校验。不一致的内容会作为验证问题报告，而不被静默接受。

• IAT（International ACH Transaction）批次及附加记录类型代码 10-18。

独立运行

npm start

服务器通过 stdio 使用 MCP 协议进行通信；不适合单独交互运行。请通过下文描述的 MCP 客户端使用它。

连接到 Claude Code

在完成构建后，从项目目录执行：

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

（在 Windows PowerShell 中： claude mcp add nacha -- node "$PWD\dist\index.js"）

连接到 GitHub Copilot（VS Code）

在你所要使用的项目中，创建 .vscode/mcp.json（如果已存在，则向其中添加），并使用连接到你本地仓库的绝对路径替换其中的路径：

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

或者，也可以从控制面板（Ctrl+Shift+P / ⇧⌘P）运行 MCP: Add Server，选择 Workspace，并使用相同的参数指向 node —— VS Code 将为你写入相同的 .vscode/mcp.json。

保存后，打开 Copilot Chat，切换到 Agent 模式，parse_nacha_file / summarize_nacha_file 工具便可使用（VS Code 会按需启动服务器）。

连接到 Claude Desktop 或其他 MCP 客户端

在客户端的 MCP 服务器配置（例如 claude_desktop_config.json）中添加一个条目，将路径改为你本地仓库的绝对路径：

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

配置添加完成后，重新启动客户端。

目录结构

• src/constants.ts — SEC 代码、交易代码、ISO 国家/地区/货币查询。

• src/format.ts — 金额 / 日期 / 时间字段解析。

• src/parser.ts — 结构验证与记录解析（文件 / 批次 / 条目 / 附加上下文）。

• src/validate.ts — 算术验证（哈希、总额、计数）。

• src/analyze.ts — 结合解析和算术验证。

• src/summarize.ts — 精简摘要视图。

• src/index.ts — MCP 服务器及工具注册。

项目的设计上不包含单元测试，以保持它成为一个小型、易于审计的服务器。

许可证

MIT — 参见 LICENSE