reconcile-mcp

reconcile-mcp：用于 ISO 20022 现金对账的 MCP 服务

一个 Model Context Protocol 服务，用于将预期付款（来自 pain.001 贷记转账）与实际观察到的已入账条目（来自 camt.053 对账单）进行匹配，并返回可解释的对账结果——包括精确匹配、少付或多付、拆分结算（一对多）、批量贷记（多对一），以及双方各自剩余的未匹配项目；每项匹配都附有评分和匹配原因。

最新版本：v0.0.7：通过 stdio、可流式传输的 HTTP 或 SSE 提供 10 个 MCP 工具；纯 Python 匹配引擎；确定性的沙盒测试模式；支持 Python 3.10+。属于 ISO 20022 MCP 套件的一部分：匹配双方都由你掌控。

为什么要开发它

对账是资金管理团队每天都要面对的难题：我们预期收到的钱是否真的到账了？每笔贷记对应哪张发票？匹配很少是一对一的——客户可能少付，分期结清发票，或者由付款聚合商汇出一笔款项，涵盖十几笔应收账款。reconcile-mcp 将这项匹配工作作为 Agent 工具提供，而且——对金融领域而言至关重要——会展示处理过程：每组匹配都附有数值评分，以及清晰列出的匹配依据（参考编号、金额、日期、交易对手）。

ISO 20022 MCP 套件

reconcile-mcp 是八个协同运作、供应商中立的 MCP 服务中的对账工作流。这些服务共同覆盖 ISO 20022 银行对账单工作流和 2026 年 11 月结构化地址切换，并提供高层编排层——就绪度评分、清算配置文件检查和审计证据——以及对账单深度分析、整个目录的路由、对账、多格式导入和地址修复。套件中的依赖版本范围保持一致，因此各服务可以在同一个 Python 环境中顺利共同安装：先从一个开始，随着工作流扩展再添加其他服务。

服务端	范围	接口	安装	适用场景
camt053-mcp	ISO 20022 camt.053/camt.052 银行对账单：解析、验证、筛选、反向转换；MT940/MT942 迁移；CBPR+ 就绪度；日记账导出	24 个 MCP 工具 · 4 个提示词 · 3 个资源	pip install camt053-mcp	你需要端到端处理银行对客户的对账单——这是套件的旗舰工具
iso20022-mcp	统一网关：search / describe / validate / generate / parse 元工具，路由至 pain · pacs · camt · acmt 系列	7 个元工具	pip install "iso20022-mcp[all]"	你希望通过一个入口访问所有消息系列
reconcile-mcp	将预期的 pain.001 付款与观测到的 camt.053 条目进行匹配——精确匹配、部分匹配、一对多、多对一；为每个匹配评分并说明原因	10 个 MCP 工具 · 1 个提示词 · 2 个资源	pip install reconcile-mcp	你需要可解释的对账单／付款对账——本软件包
bankstatementparser-mcp	多格式对账单导入：ISO 20022 CAMT.053 和 pain.001、SWIFT MT940、OFX/QFX、CSV	5 个 MCP 工具 · 1 个提示词 · 1 个资源	pip install bankstatementparser-mcp	你的对账单采用混合或旧版格式
structured-address-fix-mcp	面向 2026 年 11 月结构化地址切换的 ISO 20022 邮政地址分类、评估与修正（pacs.008 / pain.001 付款人和收款人地址）	9 个 MCP 工具	pip install structured-address-fix-mcp	你需要在 2026 年 11 月 14 日之前，使付款人／收款人地址做好切换准备
iso20022-readiness-suite-mcp	编排网关：检测 → 结构验证 → 清算配置文件规则检查 → 就绪度评分，并支持自动修正和 pacs.002 银行响应模拟——作为基础服务端之上的元客户端	4 个 MCP 工具	pip install iso20022-readiness-suite-mcp	你希望通过一个高级就绪度／编排入口访问整个套件
iso20022-bank-profile-mcp	管理、验证并提供银行专属清算配置文件／规则包（CBPR+、SEPA_Instant、FedNow、Generic）；控制高级规则包的授权	4 个 MCP 工具	pip install iso20022-bank-profile-mcp	你需要根据本机构的市场惯例检查付款规则
iso20022-evidence-pack-mcp	将就绪度检查结果、修正差异和模拟响应编译为经过封存、可通过 Ed25519 签名的审计证据包	6 个 MCP 工具	pip install iso20022-evidence-pack-mcp	你需要防篡改的审计／认证材料

每个工具各用一句话介绍：camt053-mcp 是银行对账单旗舰工具（最全面的 camt.05x 接口，支持 stdio 和经身份验证的可流式传输 HTTP）； iso20022-mcp 是通用消息工具包（通过少数几种操作覆盖 整个目录）；reconcile-mcp 是对账工作流 （预期收到的款项是否确实到账？）； bankstatementparser-mcp 是导入层（输入多种格式，输出统一的 交易结构）；而 structured-address-fix-mcp 是 邮政地址专家（让付款人／收款人地址为 2026 年 11 月切换做好准备）。

套件还包括按系列划分的服务端——pain001-mcp （贷记转账发起）、pacs008-mcp（金融机构间贷记 转账）和 acmt001-mcp（账户管理）——它们解析后的 输出可直接传入本服务端的 normalize_* 适配器。

安装

pip install reconcile-mcp
# or run without installing:
uvx reconcile-mcp

MCP 客户端配置（例如 Claude Desktop 的 claude_desktop_config.json）：

{
  "mcpServers": {
    "reconcile": {
      "command": "reconcile-mcp"
    }
  }
}

快速开始（无需真实数据）

服务提供沙盒测试模式：使用确定性场景，无需任何设置，也无需真实现金数据，即可运行完整流程。只需调用一次，即可获得完整且可解释的结果：

run_sandbox_scenario(name="month_end")

返回一个真实感十足的混合结算结果——一笔成功匹配、一笔短款、一笔拆分结算，以及一笔意外贷项（正确地保持未匹配状态）：

{
  "summary": {
    "expected_count": 3, "observed_count": 5,
    "matched_expected": 3, "unmatched_observed": 1,
    "matches_by_type": {"exact": 1, "amount_mismatch": 1, "one_to_many": 1},
    "fully_reconciled": false
  },
  "matches": [
    {"type": "amount_mismatch", "expected": ["INV-6002"], "observed": ["ENT-52"],
     "amount_delta": "-99.99", "confidence": "high",
     "reasons": ["reference exact", "amount close (delta -99.99)", "date +/-0d", "counterparty exact"]},
    {"type": "exact", "expected": ["INV-6001"], "observed": ["ENT-51"], "amount_delta": "0.00"},
    {"type": "one_to_many", "expected": ["INV-6003"], "observed": ["ENT-53", "ENT-54"],
     "reasons": ["amount sum of 2 entries"]}
  ],
  "unmatched_observed": ["ENT-55"]
}

使用 list_sandbox_scenarios 列出所有场景；使用 load_sandbox_scenario 加载场景，以检查或编辑其输入。

传输方式

一条命令行，三种传输方式：

命令	传输方式	端点	协议版本
reconcile-mcp	stdio	客户端启动进程	2026-07-28、2025-11-25
reconcile-mcp --transport streamable-http	流式 HTTP	http://127.0.0.1:8000/mcp	2026-07-28（无状态，server/discover）和 2025-11-25（initialize、Mcp-Session-Id）共用同一端点；响应以服务器发送事件的形式流式传输，GET 会打开服务器到客户端的数据流
reconcile-mcp --transport sse	HTTP+SSE（2024-11-05）	http://127.0.0.1:8000/sse 和 /messages/	面向仍需要旧版传输方式的客户端

--host 和 --port 可更改绑定地址（默认值为 127.0.0.1 和 8000）。HTTP 传输方式本身不提供身份验证：请绑定到环回地址，或在绑定到 可路由地址之前，将服务置于你信任的网关之后。每个版本都会通过 passmcp 在两个协议 版本时期使用流式 HTTP 进行验证，并通过 MCP SDK 客户端使用 SSE 进行验证；详见 ADR 0001。

{
  "mcpServers": {
    "reconcile": { "url": "http://127.0.0.1:8000/mcp" }
  }
}

使用你自己的数据

记录是简洁的规范对象——必须提供 id 和 amount，其他字段均为可选字段，可用于提高匹配准确度：

{
  "id": "INV-1001",            // your reference / end-to-end id
  "amount": 1200.00,
  "currency": "EUR",           // ISO 4217
  "date": "2026-03-02",        // ISO-8601
  "counterparty": "Acme Ltd",
  "reference": "INV-1001"      // remittance / structured reference
}

已经在使用套件中的其他工具？直接传入解析后的输出——适配器会为你完成映射：

• normalize_pain001(document) → 来自 pain001-mcp 的预期侧数据。
• normalize_camt053(document) → 来自 camt053-mcp 的实际侧数据。

然后调用 reconcile(expected, observed)。

工具

• reconcile — 将预期付款与实际条目进行匹配；生成完整且可解释的报告。
• explain_match — 根据各项信号的细分评分，对一组预期/实际记录进行匹配（用于调优）。
• normalize_pain001 — 将解析后的 pain.001 输出转换为规范的预期记录。
• normalize_camt053 — 将解析后的 camt.053 输出转换为规范的实际记录。
• list_sandbox_scenarios — 列出内置测试模式场景和特殊参考编号。
• load_sandbox_scenario — 返回一个场景的预期/实际输入，以供检查或编辑。
• run_sandbox_scenario — 加载场景并在一次调用中完成对账，是最快的首次运行方式。
• match_names_probabilistic — 根据 Jaro-Winkler 相似度对两个交易对手名称进行评分，并在达到阈值时标记为匹配。
• match_amounts_with_fx_drift — 使用给定的外汇汇率，在百分比容差范围内比较两种不同货币的金额。
• reconcile_many_to_many — 将每笔存款与一组互不重叠、金额总和等于该存款金额的发票进行匹配（子集和 ILP；需要 ilp extra）。

此外还提供一个提示词和两个资源：

• 提示词 reconcile_workflow — 分步指导如何从原始 pain.001/camt.053 得到可解释的匹配报告。
• 资源 reconcile://sandbox-scenarios — 内置场景目录。
• 资源 reconcile://sandbox/{scenario_id} — 一个场景的预期/实际输入。

匹配原理

每对候选项会根据四个加权信号评分，然后进行分类：

• 参考编号（0.45）— 参考编号和端到端 ID 完全匹配或部分匹配， 并规范化为纯字母数字字符。
• 金额（0.35）— 在容差范围内完全匹配，或按线性递减的接近程度评分， 并报告差额。
• 日期（0.10）— 在可配置的时间窗口内评估接近程度；未知时保持中性。
• 交易对手（0.10）— 名称的词元集合重叠度；未知时保持中性。

分配采用贪心算法，按分数从高到低处理，并且完全确定（使用全序的决胜规则）， 因此相同的输入始终会产生相同的结果。随后会对剩余项进行一对多（有界子集和：一笔预期款项由多笔记录结清）和多对一（一笔记录覆盖多笔预期款项）测试。

可通过 options 参数调整任何设置：abs_tol / rel_tol、 date_window_days、high_threshold、review_threshold、currency_strict、 enable_one_to_many、max_combination。

开发

git clone https://github.com/sebastienrousseau/reconcile-mcp
cd reconcile-mcp
python -m venv .venv && . .venv/bin/activate
pip install -e . && pip install pytest pytest-cov ruff black mypy
pytest                      # 100% branch coverage gate
ruff check reconcile_mcp tests && black --check reconcile_mcp tests && mypy reconcile_mcp

许可证

根据您的选择，依据 Apache License, Version 2.0 或 MIT License 获得许可。

---

mcp-name: io.github.sebastienrousseau/reconcile-mcp