bankstatementparser-mcp

bankstatementparser-mcp

一个 Model Context Protocol 服务，将 bankstatementparser 库作为一流的 Agent 工具开放，用于读取银行对账单。

目录

快速入门

• bankstatementparser-mcp 是什么？ — 它解决的问题
• ISO 20022 MCP 套件 — 四个协同工作的服务及各自的适用场景
• 安装 — PyPI、virtualenv、Docker
• 快速开始 — 30 秒内在 Claude Desktop 中注册
• 传输方式 — 通过一条命令行使用 stdio、可流式传输的 HTTP（2026-07-28 和 2025-11-25）以及 SSE

库参考

• 工具 — 五个工具、一个资源、一个提示词
• 使用工具 — 在 Python 进程中调用它们

运维

• 不适合使用 bankstatementparser-mcp 的场景 — 明确说明适用边界
• 开发 — 质量门禁、make 目标
• 安全 — 沙箱策略
• 文档 — 示例、指南
• 贡献 — 如何提交更改
• 许可证 — Apache-2.0

什么是 bankstatementparser-mcp？

模型上下文协议（MCP）是一项开放标准，可让 AI Agent 以统一的方式发现并调用外部工具。bankstatementparser-mcp 是一款 MCP 服务，可将 bankstatementparser 库转化为原生 Agent 工具，让助手能够直接在对话中读取、验证和汇总 银行对账单，支持 ISO 20022 CAMT.053、SWIFT MT940、OFX/QFX 和 CSV 等格式。

每个工具都是对 bankstatementparser 解析器核心（create_parser、detect_statement_format）的轻量封装，因此其结果与 CLI 完全一致。由于 MCP 客户端无法访问服务端的文件系统，这些工具接收 内联对账单内容（以及文件名提示），并在单次调用期间将其写入私有临时文件。工具会返回可序列化为 JSON 的数据。

ISO 20022 MCP 套件

bankstatementparser-mcp 是由八个相互协作、与供应商无关的 MCP 服务组成的套件中的 数据接入层。这些服务共同覆盖 ISO 20022 银行对账单工作流和 2026 年 11 月的结构化地址切换，包括对账单深度解析、全目录路由、对账、多格式接入和地址修复。套件中的依赖版本范围保持一致，因此这些服务可以在同一个 Python 环境中顺利共同安装：先从一个服务开始，再根据工作流的需要逐步添加其他服务。

一句话概括：camt053-mcp 是银行对账单领域的旗舰产品 （最全面的 camt.05x 功能面，支持 stdio 和经身份验证的可流式 HTTP）； iso20022-mcp 是通用消息工具包（通过少量操作覆盖整个目录）； reconcile-mcp 是对账工作流（我们预期收到的款项实际到账了吗？）； bankstatementparser-mcp 是导入层（输入多种格式， 输出统一的交易结构）；structured-address-fix-mcp 是邮政地址 专业工具（确保债务人／债权人地址在 2026 年 11 月切换前就绪）。

安装

需要 Python 3.10 或更高版本。支持 macOS、Linux 和 Windows。

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

快速开始

将服务注册到任意 MCP 客户端（以下示例使用 Claude Desktop）：

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

就这样。重启客户端后，Agent 即可使用这些工具。

默认情况下，服务通过 stdin/stdout 使用 JSON-RPC — 它旨在由 MCP 客户端启动，而非用于交互式操作。如需共享部署，请参阅传输方式。

传输方式

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

--host 和 --port 用于更改绑定地址（默认值分别为 127.0.0.1 和 8000）。HTTP 传输方式本身不提供身份验证：请绑定到 loopback 地址，或在绑定到可路由地址之前，将服务置于可信网关之后。每个版本都会通过 passmcp 在两个协议版本下验证 Streamable HTTP，并通过 MCP SDK 客户端验证 SSE；请参阅 ADR 0001。

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

工具

所有工具都委托给 bankstatementparser 解析器核心，因此其行为与该库完全一致。

• list_supported_formats — 列出解析器可读取的所有银行对账单格式
• detect_format — 检测内嵌载荷所使用的对账单格式
• parse_statement — 将对账单解析为结构化交易记录和摘要
• validate_statement — 试运行检查对账单能否顺利解析
• summarize_statement — 仅返回对账单摘要（不含逐笔交易记录）

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

• 资源 bankstatementparser://formats — 受支持格式及其文件扩展名的只读目录
• 提示词 analyze_statement — 引导式多步骤提示词，指导 Agent 读取并核对对账单

支持的格式：camt（ISO 20022 CAMT.053，.xml）、pain001（ISO 20022 pain.001，.xml）、csv（.csv）、ofx（.ofx）、qfx（.qfx）和 mt940（SWIFT MT940，.mt940 / .sta）。

使用工具

这些工具是 bankstatementparser_mcp.server 模块中的普通函数，因此可以在进程内调用：

from bankstatementparser_mcp.server import (
    detect_format,
    parse_statement,
    summarize_statement,
)

csv = (
    "date,description,amount,currency,balance\n"
    "2023-01-02,Salary,500.00,EUR,1500.00\n"
    "2023-01-03,Groceries,-40.50,EUR,1459.50\n"
)

# 1. Detect the format from the filename hint + content.
print(detect_format(csv, "statement.csv"))
# -> csv

# 2. Parse the statement into structured rows + a summary.
parsed = parse_statement(csv, "statement.csv")
print(parsed["transaction_count"], parsed["columns"])

# 3. Read just the opening/closing balances.
print(summarize_statement(csv, "statement.csv"))

资源和提示词也都是普通函数：formats_resource 对应 bankstatementparser://formats，而 analyze_statement 会返回引导式多步骤提示词。

from bankstatementparser_mcp.server import (
    analyze_statement,
    formats_resource,
)

print(formats_resource())          # the supported-formats catalogue
print(analyze_statement("statement.csv"))  # the guided analysis prompt

可在 examples/ 文件夹中查看可运行的演示，包括 04_resource_and_prompt.py。

何时不应使用 bankstatementparser-mcp

• 你使用的不是支持 MCP 的 Agent。 请直接使用 bankstatementparser CLI 或库——它提供相同的功能，调用链更简单。
• 你需要批量解析磁盘上已有的文件。 该库的 CLI 可直接读取路径，避免 MCP 工具使用的内联内容往返传输。

开发

bankstatementparser-mcp 使用 Poetry 和 mise。

git clone https://github.com/sebastienrousseau/bankstatementparser-mcp.git
cd bankstatementparser-mcp
mise install
poetry install

Makefile 用于协调质量检查关卡（与 CI 保持同步）：

当前状态（v0.0.28）：行覆盖率和分支覆盖率均为 100%，强制覆盖率下限为 100%；mypy --strict 检查通过，interrogate 覆盖率为 100%。

安全

• 工具不会持久写入文件系统。 每次调用都会将内联内容写入私有临时文件，并在调用返回后立即删除。
• validate_statement 的验证失败会以结构化的 {"is_valid": false, "error": ...} 负载形式返回，而不会返回堆栈跟踪。
• 依赖项通过 poetry.lock 固定版本，并在 CI 中使用 pip-audit 和 Bandit 进行审计。

如需报告漏洞，请使用 GitHub 私密漏洞报告， 而非公开议题。

文档

• 可运行示例： examples/
• 发布历史： CHANGELOG.md
• MCP 规范： modelcontextprotocol.io

贡献

欢迎贡献——请参阅 贡献指南。 感谢所有帮助构建 bankstatementparser-mcp 的 贡献者。

相关 MCP 服务

ISO 20022 MCP Suite 的四个核心服务已在上文 ISO 20022 MCP Suite 中进行比较。更广泛的 服务系列——面向银行和金融服务 AI Agent 的开源、Apache-2.0 许可 MCP 服务——还包括：

MCP 注册表

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

生态系统

bankstatementparser 是模块化金融生态系统的一部分。可选的配套包提供专用加载器、写入器、AI Agent、语言服务器和传输协议适配器：

Package	GitHub 仓库	PyPI	角色	描述
bankstatementparser	sebastienrousseau/bankstatementparser		核心引擎	统一解析 CAMT（052/053）、PAIN.001、CSV、OFX、QFX、MT940 和 PDF 对账单
bankstatementparser-mcp	sebastienrousseau/bankstatementparser-mcp		AI 协议	Model Context Protocol（MCP）服务，向大模型和 AI Agent 提供对账单工具
bankstatementparser-lsp	sebastienrousseau/bankstatementparser-lsp		开发者工具	Language Server Protocol（LSP），提供实时 SWIFT MT940 对账单验证和诊断
bankstatementparser-transport-ebics	sebastienrousseau/bankstatementparser-transport-ebics		传输	通过 EBICS 3.0（H005）和 2.5（H004）协议自动获取银行对账单
bankstatementparser-writer-xlsx	sebastienrousseau/bankstatementparser-writer-xlsx		输出写入器	将解析后的银行交易格式化并导出为经过样式设置的 Microsoft Excel（.xlsx）工作簿
bankstatementparser-writer-qif	sebastienrousseau/bankstatementparser-writer-qif		输出写入器	将交易序列化为标准 Quicken Interchange Format（.qif）交换文件
bankstatementparser-writer-ofx	sebastienrousseau/bankstatementparser-writer-ofx		输出写入器	将交易序列化为标准 Open Financial Exchange（.ofx）XML/SGML 文件
bankstatementparser-writer-swift	sebastienrousseau/bankstatementparser-writer-swift		输出写入器	将交易导出为 SWIFT MT940 客户对账单和 MT942 临时报告
bankstatementparser-loader-bai2	sebastienrousseau/bankstatementparser-loader-bai2		输入加载器	解析 BAI2 现金管理和账户余额对账单
bankstatementparser-loader-mt942	sebastienrousseau/bankstatementparser-loader-mt942		输入加载器	解析 SWIFT MT942 临时交易报告，并核对贷记/借记汇总
bankstatementparser-loader-cfonb	sebastienrousseau/bankstatementparser-loader-cfonb		输入加载器	解析法国 CFONB 120 / AFB120 固定宽度 120 字节银行对账单文件
bankstatementparser-loader-camt054	sebastienrousseau/bankstatementparser-loader-camt054		输入加载器	导入 ISO 20022 CAMT.054 实时借记/贷记通知流 XML
bankstatementparser-loader-sepa	sebastienrousseau/bankstatementparser-loader-sepa		输入加载器	导入 ISO 20022 SEPA PAIN.002 支付状态报告和 PAIN.008 直接借记授权
bankstatementparser-loader-bacs	sebastienrousseau/bankstatementparser-loader-bacs		输入加载器	解析英国 BACS Standard 18 / Faster Payments 固定宽度 106 字节传输文件

许可证

根据 Apache License, Version 2.0 授权。 提交以供纳入的任何贡献均应按照上述许可授权， 且不附加任何条款。

bankstatementparser.com · PyPI · GitHub