camt053-mcp

camt053-mcp：用于 ISO 20022 银行对账单的 MCP 服务

一个 Model Context Protocol 服务，将 camt053 ISO 20022 银行对账单库作为工具提供给 AI Agent 和助手使用 — 可发现消息类型和退回原因、检查输入架构、验证记录和财务标识符、解析收到的对账单，以及生成经过验证的冲销分录 XML，所有操作均可通过你喜爱的 MCP 客户端完成。

最新版本：v0.0.23：随 camt053 套件 0.0.23 一同发布 （核心库、加载器、写入器、语言服务器和此服务统一使用一个 版本）。不包含受 GHSA-84m7-p3x7-pcfv 影响的 mcp 版本，将每个 GitHub Action 固定到 SHA，并新增 CI 复杂度门禁；通过 stdio、可流式传输的 HTTP、SSE 或经过身份验证的可流式 HTTP 提供 24 个 MCP 工具。

目录

• 概览
• ISO 20022 MCP 套件
• 安装
• 快速开始
• 传输方式 — 通过一条命令行支持 stdio、可流式传输的 HTTP（2026-07-28 和 2025-11-25）、SSE 和经过身份验证的 HTTP
• 工具
• 提示词
• 资源
• 规则手册搜索
• 使用工具
• camt053 套件
• 何时不应使用 camt053-mcp
• 开发
• 安全
• 文档
• 许可证
• 贡献
• 致谢

概述

Model Context Protocol（MCP）是一项开放标准，可让 AI Agent 和助手以统一的方式发现并调用外部工具。camt053-mcp 是一个 MCP 服务，它将 camt053 库转换为一组一流的 Agent 工具，让助手能够直接在对话中读取并冲销 ISO 20022 camt.05x 现金管理报文——即标准化的银行对客户账户报告、对账单以及借记／贷记通知。

其核心功能是一站式冲销分录工作流：读取传入的 camt.053 对账单，查找带有退回原因代码（例如 AC04 账户已关闭）的分录，并生成经过验证的冲销分录。

每个工具都是对 camt053.services 的轻量级强类型封装。该服务层是 CLI 和 REST API 共用的单一门面，因此所有接口的行为完全一致。工具返回可序列化为 JSON 的数据；发生错误时，会返回 {"error": ...} 负载，而不是抛出异常。

• 网站： https://sebastienrousseau.github.io/camt053/
• 源代码： https://github.com/sebastienrousseau/camt053-mcp
• 错误报告： https://github.com/sebastienrousseau/camt053-mcp/issues

此软件包是 camt053 套件的一部分。该套件由一组可独立安装的软件包组成，共用 camt053.services 层：

• camt053 — 核心库（CLI + REST API）
• camt053-mcp — 本软件包，即 Model Context Protocol 服务
• camt053-lsp — 面向编辑器的 Language Server Protocol 服务

flowchart LR
    A["MCP client<br/>(Claude Desktop, IDE, agent)"] -->|stdio| B["camt053-mcp"]
    B -->|delegates to| C["camt053.services"]
    C -->|parse + reverse + validate| D["ISO 20022 camt.053 XML"]

ISO 20022 MCP 套件

camt053-mcp 是八个协同运作、供应商中立的 MCP 服务中的银行对账单旗舰服务。这些服务共同覆盖 ISO 20022 银行对账单工作流及 2026 年 11 月结构化地址切换，涵盖对账单深度、全目录路由、对账、多格式摄取和地址修复。套件内各服务的依赖版本范围保持一致，因此可以在同一个 Python 环境中顺利共同安装：先从一个服务开始，随着工作流扩展再添加其他服务。

一句话概括：camt053-mcp 是银行对账单旗舰产品 （提供最全面的 camt.05x 接口，支持 stdio、可流式传输的 HTTP、SSE 和经过身份验证的可流式传输 HTTP）； iso20022-mcp 是通用报文工具包（用少量动词覆盖整个目录）；reconcile-mcp 是对账工作流（预期的款项是否实际到账？）； bankstatementparser-mcp 是数据接入层（接收多种格式，输出统一的交易结构）；而 structured-address-fix-mcp 是邮政地址专家（确保债务人／债权人地址在 2026 年 11 月切换前满足要求）。

套件还包含按报文系列划分的服务端—— pain001-mcp （贷记转账发起）、 pacs008-mcp （金融机构间贷记转账），以及 acmt001-mcp （账户管理）——均可通过 iso20022-mcp 网关访问。

安装

camt053-mcp 可在 macOS、Linux 和 Windows 上运行，需要 Python 3.10+ 和 pip。它会自动安装核心 camt053 库和 MCP SDK。

python -m pip install camt053-mcp

python -m venv venv
source venv/bin/activate        # macOS/Linux
venv\Scripts\activate           # Windows
python -m pip install -U camt053-mcp

10 分钟安装 → MCP 客户端配置 → 首次对话教程，请参阅 docs/quickstart.md。

通过 stdio 启动服务（FastMCP 默认传输方式）：

camt053-mcp

将其添加到客户端的配置中，即可向任意 MCP 客户端（例如 Claude Desktop）注册：

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

之后，Agent 可以按需调用以下工具来解析收到的对账单并生成经过验证的反向分录。

对于共享的多租户部署，服务也可以使用可流式传输的 HTTP，并强制进行 bearer-token 身份验证，还可按请求使用 Camt053-Account 指定租户范围：

CAMT053_MCP_TOKEN=<secret> camt053-mcp --transport=http --bind=0.0.0.0:8080

请参阅多租户 HTTP 部署 和部署指南。

传输方式

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

--host 和 --port 可更改 streamable-http 和 sse 的绑定地址（默认值分别为 127.0.0.1 和 8000）。这两种方式本身都不提供身份验证：请绑定到环回地址，或在绑定到可路由地址之前，将服务置于可信网关后；--transport http 是经过身份验证的选项。每个版本都会使用 scout 验证两种协议时期下的可流式传输 HTTP，并使用 MCP SDK 客户端验证 SSE；请参阅 ADR 0001。

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

工具

所有工具都委托给共享的 camt053.services 层，因此其行为与 CLI 和 REST API 完全一致。

• list_message_types — 列出支持的 3 种 camt.05x 消息类型
• list_return_reasons — 列出 ISO 外部退汇原因代码
• get_required_fields — 指定消息类型所需的输入字段
• get_input_schema — 指定消息类型的完整输入 JSON Schema
• validate_records — 根据消息类型验证扁平记录
• validate_identifier — 验证 IBAN、BIC 或 LEI
• validate_statement — 根据其 XSD 验证对账单并检测其类型
• convert_mt940_to_camt053 — MT940 → camt.053 迁移：将旧版 SWIFT MT940 对账单文本转换为 camt.053 结构
• convert_mt942 — MT942 → camt.052 迁移：将旧版 SWIFT MT942 中间交易报告文本转换为 camt.052 结构
• check_cbpr_readiness — 标记对账单中 CBPR+ 于 2026 年 11 月截止时存在的问题
• get_cbpr_cutover_date — 返回 CBPR+ 官方切换日期（2026-11-16）
• cite_rulebook — 引用精选的 SEPA / CBPR+ / HVPS+ 规则手册条款
• list_rulebook_clauses — 列出可用的规则手册引文（可选择筛选）
• search_rulebook_vector — 当你不知道条款 ID 时，通过自然语言相似度查找规则手册条款（需要 [vector] extra）
• export_journal — 将对账单分录导出为 Xero BankTransactions 或 QBO JournalEntry 负载
• list_export_journal_targets — 列出 export_journal 支持的会计平台目标
• classify_entry — 通过 MCP Sampling 对对账单分录进行分类（使用客户端的大模型）
• list_classify_entry_categories — 列出 classify_entry 使用的默认类别
• get_tenant_context — 报告调用的多租户范围（HTTP 传输中的 Camt053-Account 标头；stdio 传输时为 None）
• parse_statement — 将传入的 camt.05x 对账单解析为数据
• detect_statement_anomalies — 检查对账单中的重复参考信息、异常费用扣款和频率激增（使用确定性规则，不使用模型或网络）
• list_entries — 列出所有对账单中的每条分录（分页）
• filter_entries — 返回带有退汇原因代码的分录（分页）
• generate_reversal — 生成经过验证的冲正分录 XML 文档

分页

list_entries 和 filter_entries 接受可选的 offset（默认值为 0）和 limit（默认值为 None）参数。省略 limit 时，它们会像以前一样返回 完整列表。指定 limit 时，它们会改为返回分页封装：

{"total": 42, "offset": 10, "limit": 5, "entries": [/* ... */]}

负数 offset 或 limit 会返回 {"error": ...} 负载，与 服务端其余部分的错误约定一致。

提示词

reversal_preview 接受可选的 reason_code（默认值为 "AC04"），并返回一个四步消息模板：解析对账单、使用 filter_entries 预览匹配的分录、向操作员确认，然后调用 generate_reversal。其余三个提示词不接受参数，并返回由用户提示词和助手引导说明组成的双消息模板，Agent 可以原样重放。

资源

资源为 Agent 提供只读参考上下文，可直接加载，无需调用工具。每个资源都会返回一个 JSON 负载。

两者都基于共享的 camt053.services 层，因此会与对应的 list_return_reasons / list_message_types 工具保持同步。发生错误时，它们会返回序列化的 {"error": ...} 负载。

规则手册搜索

cite_rulebook 需要 scheme、version 和 clause ID。当你知道规则涉及什么，但不知道它叫什么时，search_rulebook_vector 可以帮你找到答案：

search_rulebook_vector("structured address requirement", top_k=3)
{
  "query": "structured address requirement",
  "returned": 3,
  "results": [
    {
      "scheme": "HVPS+",
      "version": "2026",
      "clause": "structured-address-alignment",
      "title": "HVPS+ aligns with CBPR+ structured-address rule",
      "score": 0.702729,
      // ...
    }
  ]
}

获取排名最高的 scheme/version/clause，并传给 cite_rulebook，以获取完整引用。

**它不是神经嵌入模型。**检索采用确定性的词汇向量余弦搜索：每个条款和查询都会被哈希为固定的 256 维词频向量 — 包含完整单词以及 3 元和 4 元字符 n-gram，因此 address 可以匹配 addresses，无需词干提取器 — 使用 BLAKE2b 分桶，而不是 Python 的加盐 hash，并通过 sqlite-vec 排名。这会带来以下三个值得注意的结果：

• 同一个查询在任何进程和每次 CI 运行中，始终返回相同的排名。
• 不会下载任何内容，查询时也不会发起网络调用。
• 它匹配措辞，而非含义。如果查询与某个条款没有共同词汇，无论概念多么相关，都无法找到该条款。

索引仅涵盖经过整理的摘要 — 与 cite_rulebook 使用的摘要相同。不会存储或搜索外部、受版权保护或需要身份验证才能访问的规则手册文本。

安装

sqlite-vec 随可选额外依赖提供，并采用延迟导入，因此基础安装不会引入任何依赖：

python -m pip install 'camt053-mcp[vector]'

如果没有安装该依赖，工具会返回一条注明额外依赖名称的普通错误负载，而不是引发异常。因此，在基础安装上调用该工具的客户端会收到可用的提示，而非堆栈跟踪。

还有一项容易忽略的要求：你的 Python 必须在构建时启用可加载的 SQLite 扩展支持。python.org 的 macOS 安装程序和一些发行版软件包默认禁用了此功能；在这种情况下，即使 sqlite-vec 安装成功，仍然无法加载。工具会检测到这一点并说明原因，同时指出需要查找的构建标志（--enable-loadable-sqlite-extensions）。Homebrew、uv 和 pyenv 构建通常已启用此功能。

如需了解检索设计及其限制，请参阅 docs/vector-search.md。

使用工具

你可以直接通过 FastMCP 实例在进程内调用工具 — 无需使用传输层。这与 Agent 通过 stdio 接收工具的方式一致。此代码片段的可运行版本位于 examples/mcp_tools.py。

import asyncio

from camt053_mcp.server import server

# A complete camt.053 statement with one entry returned AC04 (Closed Account).
statement_xml = """<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:camt.053.001.14">
  <BkToCstmrStmt>
    <GrpHdr><MsgId>STMT-MSG-0001</MsgId><CreDtTm>2026-06-15T08:00:00</CreDtTm></GrpHdr>
    <Stmt>
      <Id>STMT-0001</Id><CreDtTm>2026-06-15T08:00:00</CreDtTm>
      <Acct><Id><IBAN>GB29NWBK60161331926819</IBAN></Id><Ccy>EUR</Ccy></Acct>
      <Bal><Tp><CdOrPrtry><Cd>CLBD</Cd></CdOrPrtry></Tp>
        <Amt Ccy="EUR">10000.00</Amt><CdtDbtInd>CRDT</CdtDbtInd>
        <Dt><Dt>2026-06-15</Dt></Dt></Bal>
      <Ntry>
        <NtryRef>NTRY-0001</NtryRef>
        <Amt Ccy="EUR">1500.00</Amt><CdtDbtInd>CRDT</CdtDbtInd>
        <Sts><Cd>BOOK</Cd></Sts>
        <NtryDtls><TxDtls>
          <RtrInf><Rsn><Cd>AC04</Cd></Rsn></RtrInf>
        </TxDtls></NtryDtls>
      </Ntry>
    </Stmt>
  </BkToCstmrStmt>
</Document>"""


async def main() -> None:
    async def call(name, args):
        result = await server.call_tool(name, args)
        # mcp 2.x returns a CallToolResult (read .content); 1.x
        # returns the content list, or a (content, meta) tuple.
        content = getattr(result, "content", None)
        if content is None:
            # mcp 2.x returns a CallToolResult (read .content); 1.x
            # returns the content list, or a (content, meta) tuple.
            content = getattr(result, "content", None)
            if content is None:
                content = result[0] if isinstance(result, tuple) else result
        return content[0].text if content else ""

    # Validate an identifier.
    print(await call("validate_identifier",
                     {"kind": "bic", "value": "NWBKGB2LXXX"}))
    # -> {"kind": "bic", "value": "NWBKGB2LXXX", "valid": true}

    # Page through the matching entries (paginated envelope).
    print(await call("filter_entries",
                     {"xml": statement_xml, "reason_code": "AC04",
                      "offset": 0, "limit": 5}))
    # -> {"total": 1, "offset": 0, "limit": 5, "entries": [...]}

    # Generate a validated reversing-entry document for the AC04 entries.
    xml = await call("generate_reversal",
                     {"xml": statement_xml, "reason_code": "AC04"})
    print(xml[:46])  # -> <?xml version="1.0" encoding="UTF-8"?> ...


asyncio.run(main())

直接运行：

python examples/mcp_tools.py

camt053 套件

camt053-mcp 是一组围绕 camt053 库构建、可独立安装的软件包之一——根据你的技术栈选择所需的软件包：

这里的每个工具都是对 camt053.services 的轻量类型化封装——CLI、REST API 和 LSP 使用的也是同一个门面——因此四种接口的行为完全一致。

何时不应使用 camt053-mcp

• 你没有 MCP 客户端。 此服务只有搭配支持 MCP 的宿主（Claude Desktop、IDE 插件、Agent 框架）才有意义。对于脚本或 CI 场景，camt053 CLI 和 REST API 无需 stdio 协议开销即可实现相同功能。
• 你需要在没有 MCP 客户端的情况下将其作为长期运行的守护进程。 此服务确实可以通过 streamable HTTP 传输（--transport=http）持久运行，但每个使用方仍必须使用 MCP JSON-RPC。若需要普通的 REST 语义，请使用 camt053 FastAPI 服务。
• 你需要流式响应。 工具调用返回完整值，而不是数据流。较大的对账单通过现有的 list_entries(xml, offset, limit) 信封分页，而不是拆分为多个响应块。
• 你需要由服务代为处理面向每位用户的 OAuth 流程。 HTTP 传输会对调用方进行身份验证（使用 RFC 9728 元数据的 OAuth 2.1 资源服务器，或开发模式下的静态 bearer token），并通过 Camt053-Account 租户标头限定请求范围，但它不运行授权服务器：请自备 IdP。
• 你需要生成出站 pain.001 支付文件。 此功能不在范围内；请使用 pain001-mcp。

开发

camt053-mcp 使用 Poetry 和 mise。

git clone https://github.com/sebastienrousseau/camt053-mcp.git && cd camt053-mcp
mise install
poetry install
poetry shell

Makefile 负责协调质量门禁（与 CI 保持同步）：

make check        # all gates (REQUIRED before commit)
make test         # pytest
make lint         # ruff + black
make type-check   # mypy --strict

安全

camt053-mcp 是一个轻量封装——每个工具都会委托给 camt053.services，纵深防御措施（defusedxml + xml_guard 字节数上限 + DOCTYPE / ENTITY 预检）都在其中。工具会捕获 (ValueError, Camt053Error)，并按照套件约定返回 {"error": ...} 信封；它们绝不会将原始异常传播给 MCP 客户端。报告流程、支持的版本和完整的供应链安全状况见 SECURITY.md。漏洞请通过 GitHub Private Vulnerability Reporting 报告，不要在公开议题中披露。

文档

• README.md — 本文件
• CHANGELOG.md — 发行说明
• SECURITY.md — 漏洞披露与支持的版本
• SUPPORT.md — 获取帮助的方式
• MAINTAINERS.md — 有权合并代码的人员
• examples/ — 可运行的脚本
• glama.json — Glama 目录清单
• docs/iso20022-mcp-servers-compared.md — ISO 20022 MCP 服务对比（2026）
• docs/BENCHMARKS.md — 实测 HTTP 负载基准
• Glama 条目：https://glama.ai/mcp/servers/sebastienrousseau/camt053-mcp

相关 MCP 服务

属于 ISO 20022 MCP 套件——面向银行和金融服务 AI Agent 的开源、采用 Apache-2.0 许可的 MCP 服务：

MCP 注册表

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

许可证

采用 Apache License, Version 2.0 或 MIT License 双重许可。提交以供纳入的任何贡献均须按上述许可授权，且不得附加其他条款。

贡献

欢迎贡献——请参阅贡献指南。感谢所有贡献者。

致谢

基于 camt053 ISO 20022 银行对账单库和 Model Context Protocol Python SDK 构建。