iso20022-mcp

iso20022-mcp

一个 MCP 服务，包含七个元工具，可将请求路由到所有 ISO 20022 消息系列。

---

目录

快速开始

• 安装 — 各系列对应的 pip extras、uvx、MCP 客户端配置
• 要求 — 工具链最低要求、平台
• 快速入门 — 通过一个服务进行搜索、描述、验证、生成和解析

iso20022-mcp 生态系统

• iso20022-mcp 生态系统 — ISO 20022 MCP Suite 及此网关路由到的系列服务

库参考

• 功能一览 — 按主题列出的当前功能
• 生态系统对比 — 简要矩阵；完整表格见 docs/COMPARISON.md
• 基准测试 — 主要数据；完整表格见 docs/BENCHMARKS.md
• 功能 — 模块级功能列表
• 配置 — 核心选项
• 示例 — 可运行示例索引

运维

• 何时不应使用 iso20022-mcp — 局限性
• 开发 — make 目标、模糊测试、CI
• 安全 — 保障与合规性
• 文档 — 所有参考文档
• 稳定性保证 — SemVer 维度、输出稳定性、工具链最低版本规范
• 许可证

---

安装

作为 Python 库

pip install "iso20022-mcp[all]"

最新版本：v0.0.18：通过 stdio、可流式传输的 HTTP 或 SSE（可选使用 HTTPS）提供 7 个路由元工具，核心轻量（仅依赖 mcp）， 后端系列服务作为可选 extras 提供；每次 validate/generate 失败时， 都会返回可执行的结构化错误信息，支持 Python 3.10+。

核心轻量。按需添加所需系列的 extras：

pip install "iso20022-mcp[pacs,camt]" # just interbank + statements
pip install iso20022-mcp              # core only; families report as not installed
uvx --from "iso20022-mcp[all]" iso20022-mcp   # run without installing

MCP 客户端配置（例如 Claude Desktop）：

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

---

要求

• Python 3.10 或更高版本；CI 已在 Linux 上使用 3.10、3.11、3.12、3.13 和 3.14 进行测试（工具链政策）。
• mcp 1.x 系列需为 1.30 或更高版本，或 2.x 系列需为 2.2 或更高版本。受 GHSA-84m7-p3x7-pcfv 影响的版本无法解析。
• 各系列服务均为可选扩展：pain、pacs、camt、acmt 或 all。

---

快速开始

search(query="reconciliation")
  → [{ "message_type": "camt.053", "family": "camt", "package": "camt053-mcp" }]

describe(message_type="pacs.008")           # required fields + input schema
validate(message_type="pacs.008", records=[…])
generate(message_type="pain.001", records=[…])   # → { "xml": "<Document>…" }
  # bare "pain.001" resolves to pain.001.001.09; on failure the payload is
  # { "error": "Missing required fields for pain.001.001.09: …" } listing
  # every missing or invalid field at once — fix them all and retry once
parse(message_type="camt.053", xml="<Document>…")
  # parse covers pacs + camt only; pain and acmt are outbound-only

先使用 search 或 list_families 查找消息类型，再通过 describe 查看其必填字段和输入架构，然后调用 validate、generate 或 parse。每次调用都会根据消息类型的前缀路由至相应的系列服务。

---

iso20022-mcp 生态系统

iso20022-mcp 是 ISO 20022 MCP Suite 的通用消息工具包：由八个协同工作的、厂商中立的 MCP 服务组成，涵盖 ISO 20022 银行对账单工作流和 2026 年 11 月结构化地址切换，并提供用于就绪度评分、清算配置文件检查和审计证据的编排层。整个套件的依赖范围保持一致，因此各服务可以在同一个 Python 环境中顺利共存：从一个开始，随着工作流扩展再添加其他服务。

组件	用途	使用场景
camt053-mcp	ISO 20022 camt.053/camt.052 银行对账单：解析、验证、筛选、反向处理；MT940/MT942 迁移；CBPR+ 就绪度；日记账导出（24 个工具、4 个提示词、3 个资源）	你需要端到端处理银行与客户之间的对账单；这是套件的旗舰组件
iso20022-mcp	统一网关：将 search / describe / validate / generate / parse 元工具路由至 pain · pacs · camt · acmt 系列（7 个元工具）	你希望通过一个入口访问所有消息系列：本软件包
reconcile-mcp	将预期的 pain.001 付款与实际观察到的 camt.053 条目进行匹配：精确匹配、部分匹配、一对多、多对一，并为每次匹配评分和说明原因（7 个工具）	你需要可解释的对账单与付款核对
bankstatementparser-mcp	多格式对账单导入：ISO 20022 CAMT.053 和 pain.001、SWIFT MT940、OFX/QFX、CSV（5 个工具、1 个提示词、1 个资源）	你的对账单采用混合格式或旧格式
structured-address-fix-mcp	面向 2026 年 11 月结构化地址切换的 ISO 20022 邮政地址分类、评估和修正（9 个工具）	你需要在 2026 年 11 月 14 日前准备好债务人/债权人地址
iso20022-readiness-suite-mcp	编排：检测、验证、清算配置文件检查和就绪度评分，以及修正和 pacs.002 响应模拟（4 个工具）	你希望通过一个高级入口获取整个套件的就绪度信息
iso20022-bank-profile-mcp	管理、验证和提供银行清算配置文件及规则包（CBPR+、SEPA_Instant、FedNow、Generic）（4 个工具）	你需要根据所在机构的市场惯例检查付款
iso20022-evidence-pack-mcp	将发现结果、修正差异和模拟响应汇编为密封的审计证据包，可使用 Ed25519 签名（6 个工具）	你需要具备防篡改能力的审计或认证材料
pain001-mcp、pacs008-mcp、acmt001-mcp、camt-exceptions	此网关所路由到的各系列专用服务，以扩展形式安装	iso20022-mcp[all] 会为你安装这些服务；请参阅功能

---

功能一览

领域	功能	状态
发现	在整个目录中使用 search、list_families、list_servers	已发布；核心安装即可使用
架构	describe 返回必填字段和输入 JSON Schema	已发布；需要安装相应系列的附加包
验证	validate 根据消息类型的架构检查记录	已发布；适用于所有系列
生成	generate 为 pain、pacs、acmt 和 camt.056/camt.029 生成经验证的 XML	已发布
解析	parse 读取传入的 pacs 和 camt XML	已发布；pain 和 acmt 仅支持出站
传输	stdio、可流式传输的 HTTP 和 SSE，可选 HTTPS	已发布；自 0.0.18 起支持 HTTPS

---

生态系统对比

此网关的替代方案是让 Agent 直接连接每个系列的服务。 以下数据于 2026-10-20 通过 stdio 使用 list_tools 测得：

项目	需配置的服务数	Agent 可见的工具数	估算目录 token 数
iso20022-mcp	1	7	~2,200
直接连接全部四个系列的服务	4	73	~36,400

证据和完整对比表请参见 docs/COMPARISON.md。

---

基准测试

路由耗时仅为微秒级；每个进程首次调用某个系列时，会执行一次延迟导入。使用 benches/bench_gateway.py --quick 测得。

场景	结果	环境
family_for 路由	0.54 µs	Apple A18 Pro，Python 3.12.15，mcp 2.3.0
search_catalog	7.29 µs	Apple A18 Pro，Python 3.12.15，mcp 2.3.0
首次调用 pain.001（冷导入）	528 ms	Apple A18 Pro，Python 3.12.15，全新解释器
后续调用 pain.001（热调用）	5.04 µs	Apple A18 Pro，Python 3.12.15

方法和完整结果请参见 docs/BENCHMARKS.md。

---

功能

7 个路由元工具：

• search — 按用例／关键词查找消息类型（“reconciliation”、“pacs.008”）。（系列：全部 — 目录）
• list_families — 列出系列、其功能以及已安装的后端包。（系列：全部）
• list_servers — 完整套件映射：系列 + E&I 消息 + 专用服务（reconcile、agent-payment bridge）。（系列：全部）
• describe — 返回消息类型的必填字段和输入 JSON Schema。（系列：全部）
• validate — 根据消息类型的架构验证记录。（系列：全部）
• generate — 根据记录生成经过验证的 ISO 20022 XML 消息。（系列：pain · pacs · acmt）
• parse — 将传入的 ISO 20022 XML 消息解析为结构化数据。（系列：pacs · camt）

操作会根据功能支持情况执行：对 camt.053 对账单（一种传入格式）调用 generate 时，会返回清晰易懂的错误，而不是含糊地失败；对于每种“未安装软件包”的情况，都会明确告知需要执行哪条 pip install 命令。

路由支持的各系列均具备以下三项易用性保障：

• 可操作的结构化错误。 后端服务引发的任何错误—— 不仅限于它返回的错误——都会以 {"error": "<Type>: <message>"} 负载的形式传递给 Agent，而不是显示不透明的 工具执行失败。对于 pain 生成，错误会一次性列出所有 缺失或无效字段，因此修正后重试一次即可。
• message_type 系列别名。 仅提供系列名称时，会由后端服务解析为具体版本：pain.001 → pain.001.001.09、pain.008 → pain.008.001.02。如果已知完整版本类型，仍建议优先使用。
• 预先说明各系列的解析支持范围。 parse 仅支持传入系列：pacs（例如 pacs.008）和 camt（例如 camt.053）。发起系列 pain 和 acmt 仅支持出站——此处没有对应的解析器，因此不要尝试对 pain.001 或 acmt.001 执行生成→解析往返；请改用 validate （或后端服务的 XSD 验证）。

路由

前缀	系列	后端服务	generate	parse
pain	客户贷记转账发起	pain001-mcp	✅	—
pacs	金融机构间客户贷记转账	pacs008-mcp	✅	✅
camt	银行对客户对账单	camt053-mcp	—	✅
acmt	开户指令	acmt001-mcp	✅	—
camt.056/camt.029	取消 / 解决（E&I）	camt-exceptions	✅	—

generate("camt.056.001.12", …) 会路由到 camt-exceptions。网关还会通过 search 和 list_servers 提供专用服务 — reconcile-mcp 和 ap2-iso20022 — 供发现使用 （它们通过各自的工具调用）。

网关会延迟且按需导入每个后端服务 — 核心仅依赖 mcp，并在首次使用时加载相应系列的服务。消息 类型根据其前缀匹配（pacs.008.001.08 → pacs）。pain 附加依赖要求 pain001-mcp >= 0.0.56，该版本提供了便于大模型使用的 generate 接口（字段别名、计算得出的 nb_of_txs / ctrl_sum、一次性返回所有字段错误），网关的保证正是基于此构建的。

---

配置

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

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

--host 和 --port 用于更改绑定地址（默认值分别为 127.0.0.1 和 8000）。在 mcp 1.x 和 2.x 中，--ssl-certfile cert.pem --ssl-keyfile key.pem 均可让任一 HTTP 传输方式改用 HTTPS。HTTP 传输方式本身不提供身份验证：请绑定到环回地址，或在绑定到可路由地址之前，将服务置于你信任的网关之后。每个版本都会通过 passmcp 在两个协议时期的 Streamable HTTP 上进行验证，并通过 MCP SDK 客户端在 SSE 上进行验证；详见 ADR 0001。

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

运行 iso20022-mcp --help 查看所有选项。

---

示例

• examples/mcp_tools.py：使用核心安装进行发现，然后调用路由后的 describe、validate、generate 和 parse（安装 pip install -e ".[all]" 后运行 python examples/mcp_tools.py）。
• benches/bench_gateway.py：查看网关在各系列服务之上增加了什么。
• 如需使用专用引擎，将 camt.053 对账单与预期的 pain.001 付款进行匹配，请参见 reconcile-mcp。

---

何时不应使用 iso20022-mcp

• 你需要某个系列的专用工具。 网关提供各系列共有的操作。例如，camt053-mcp 的 MT940 迁移或日记账导出功能仅在该服务上提供：请直接连接该服务。
• 你需要对 pain 或 acmt 进行往返解析。 这里仅支持向外生成，不提供解析器。
• 你需要银行、结算引擎或付款审批人。 此工具会路由和验证消息；它不会将任何内容发送到任何地方，也不提供银行认证。
• 你需要为 HTTP 传输方式启用身份验证。 内置功能不提供身份验证；请在前面部署一个带身份验证的网关。

---

开发

git clone https://github.com/sebastienrousseau/iso20022-mcp
cd iso20022-mcp
python -m venv .venv && . .venv/bin/activate
make dev
make check                         # lint, mypy strict, tests, version agreement
python benches/bench_gateway.py --quick

make check 会运行 ruff、black、严格模式下的 mypy、pytest（后端均使用伪实现），并执行要求行覆盖率和分支覆盖率达到 100% 的门槛，以及版本一致性检查。 CI 还会运行 CodeQL、OpenSSF Scorecard、reuse lint、MCP Inspector、Hypothesis 属性测试，以及对每个工具进行 Atheris 模糊测试（每次变更运行两分钟，每周运行 30 分钟）。请参阅 DEVELOPMENT.md 和 CONTRIBUTING.md。

---

安全

工具均为只读、幂等且采用封闭世界设计：没有工具会打开路径、URL 或套接字，而且每次调用都会通过一个注册表表格进行路由，因此调用方输入不会传递给导入操作。Stdio 是默认方式；HTTP 传输绑定到环回地址，可提供 HTTPS 服务，且自身不带身份验证。发布版本从签名标签可复现地构建，并提供 SLSA 来源证明和可供验证的 sigstore 签名。威胁模型和证据见安全保证案例和安全审查。该项目已获得 OpenSSF 最佳实践 通过徽章。

请按照 SECURITY.md 报告漏洞。

---

文档

用户手册 · API 参考：工具 · 开发者指南 · 架构 · 系列项目图 · 变更日志 · 路线图

---

稳定性保证

本项目尚未达到 1.0 版本，版本号以 0.0.1 为步长递增。破坏性变更的判定范围是 Agent 所看到的 MCP 接口：工具名称、参数以及返回内容的结构（包括 {"error": ...} 载荷）。即使 Python 签名没有变化，对其中任一项的修改也属于破坏性变更，并会在变更日志中说明。生成的 XML 来自系列服务，并遵循各自的稳定性规则。Python 最低版本仅会按照工具链政策所述进行调整。

---

许可证

本项目采用双许可证，您可以选择以下任一许可证：

• Apache License，Version 2.0（LICENSE-APACHE 或 https://www.apache.org/licenses/LICENSE-2.0）
• MIT License（LICENSE-MIT 或 https://opensource.org/licenses/MIT）

依赖项各自遵循其许可证。

徽标名为“Computer connected”，由 glyph.faisalovers 创作，来自 Noun Project，依据 CC BY 3.0 授权，并针对浅色和深色主题重新着色。

---

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