camt053-mcp: An MCP Server for ISO 20022 Bank Statements

camt053-mcp: An MCP Server for ISO 20022 Bank Statements

A Model Context Protocol server that exposes the camt053ISO 20022 Bank Statement library as tools for AI agents and assistants —discover message types and return reasons, inspect input schemas, validaterecords and financial identifiers, parse incoming statements, and generatevalidated reversing-entry XML, all from your favourite MCP client.

Latest release: v0.0.5 — ten MCP tools over stdio, all backed by theshared camt053.services layer, for Python 3.10+.See what's new →

Contents

• Overview
• Install
• Quick Start
• Tools
• Prompts
• Resources
• Using the tools
• The camt053 suite
• When not to use camt053-mcp
• Development
• Security
• Documentation
• License
• Contributing
• Acknowledgements

Overview

The Model Context Protocol (MCP) is an open standard that lets AI agentsand assistants discover and call external tools in a uniform way. camt053-mcpis an MCP server that turns the camt053 library into a set offirst-class agent tools, so an assistant can read and reverse ISO 20022camt.05x cash-management messages — the standardised bank-to-customeraccount reports, statements, and debit/credit notifications — directly from aconversation.

The headline capability is the one-shot reversing-entry workflow: read anincoming camt.053 statement, find the entries carrying a return reason code(e.g. AC04 Closed Account), and emit a validated reversing entry.

Every tool is a thin, typed wrapper over camt053.services — the single sharedfacade also used by the CLI and REST API — so all interfaces behave identically.Tools return JSON-serialisable data; on an error they return an{"error": ...} payload rather than raising.

• Website: https://sebastienrousseau.github.io/camt053/
• Source code: https://github.com/sebastienrousseau/camt053-mcp
• Bug reports: https://github.com/sebastienrousseau/camt053-mcp/issues

This package is part of the camt053 suite — a set of independentlyinstallable packages that share the camt053.services layer:

• camt053 — the core library (CLI + REST API)
• camt053-mcp — this package, the Model Context Protocol server
• camt053-lsp — the Language Server Protocol server for editors

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

Install

camt053-mcp runs on macOS, Linux, and Windows and requires Python 3.10+and pip. It pulls in the core camt053 library and the MCP SDKautomatically.

python -m pip install camt053-mcp

Note: while the core camt053 library is not yet on PyPI, install it fromsource first:

python -m pip install "git+https://github.com/sebastienrousseau/camt053.git"
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

Quick Start

For the 10-minute install → MCP client config → first conversationtutorial, see docs/quickstart.md.

Launch the server over stdio (the FastMCP default transport):

camt053-mcp

Register it with any MCP client (e.g. Claude Desktop) by adding it to theclient's configuration:

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

The agent can then call the tools below to parse incoming statements andgenerate validated reversing entries on demand.

Tools

All tools delegate to the shared camt053.services layer, so they behaveidentically to the CLI and REST API.

Pagination

list_entries and filter_entries accept optional offset (default 0) andlimit (default None) parameters. When limit is omitted they return thefull list, exactly as before. When limit is given they return a paginatedenvelope instead:

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

A negative offset or limit returns an {"error": ...} payload, consistentwith the rest of the server's error convention.

Prompts

reversal_preview takes an optional reason_code (default "AC04") andreturns a four-step message template: parse the statement, preview the matchingentries with filter_entries, confirm with the operator, then callgenerate_reversal. The other three prompts take no parameters and return atwo-message user-prompt + assistant-walkthrough template the agent can replayverbatim.

Resources

Resources give an agent read-only reference context it can load withoutcalling a tool. Each resource returns a JSON payload.

Both back onto the shared camt053.services layer, so they stay in sync withthe equivalent list_return_reasons / list_message_types tools. On an errorthey return a serialised {"error": ...} payload.

Note: A validate_statement MCP tool is deferred to a later release —it depends on a core camt053.services.validate_statement API that ships withcamt053 0.0.2.

Using the tools

You can invoke the tools in-process — without a transport — straight through theFastMCP instance. This mirrors what an agent receives over stdio. The runnableversion of this snippet lives in 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)
        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())

Run it directly:

python examples/mcp_tools.py

The camt053 suite

camt053-mcp is part of a set of independently installable packagesbuilt around the camt053 library — pick whichever onesyour stack needs:

Every tool here is a thin typed wrapper over camt053.services —the same facade the CLI, REST API, and LSP use — so all fourinterfaces behave identically.

When not to use camt053-mcp

• You have no MCP client. This server only makes sense pairedwith an MCP-aware host (Claude Desktop, the IDE plugins, an agentframework). For scripted / CI use, the camt053 CLI and REST APIcover the same ground without the stdio protocol overhead.
• You need to run as a long-lived daemon. This server speaks MCPstdio: an MCP client launches it as a subprocess, sends JSON-RPCover stdin / stdout, and shuts it down. A persistent worker is notthe right pattern.
• You need streaming responses. Tool calls return whole values,not streams. Large statements are paginated through the existinglist_entries(xml, offset, limit) envelope, not chunked overmultiple responses.
• You need authentication. This server has no auth; it isdesigned to run as a local subprocess inside an MCP client.Multi-tenant / network deployments need a proxy layer in front.
• You need to generate pain.001 outbound payment files. Out ofscope; use pain001-mcp.

Development

camt053-mcp uses Poetry andmise.

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

This package depends on the core camt053 library. Until it is on PyPI,install it from source first:pip install "git+https://github.com/sebastienrousseau/camt053.git".

A Makefile orchestrates the quality gates (kept in lockstep with CI):

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

Security

camt053-mcp is a thin wrapper — every tool delegates tocamt053.services, where the defence-in-depth (defusedxml +xml_guard byte cap + DOCTYPE / ENTITY pre-flight) lives. Toolscatch (ValueError, Camt053Error) and return an {"error": ...}envelope per the suite convention; they never propagate rawexceptions to the MCP client. Reporting practice, supportedversions, and the full supply-chain posture are documented inSECURITY.md. Vulnerabilities go via GitHub PrivateVulnerability Reporting, not public issues.

Documentation

• README.md — this file
• CHANGELOG.md — release notes
• SECURITY.md — disclosure + supported versions
• SUPPORT.md — how to get help
• MAINTAINERS.md — who can merge
• examples/ — runnable scripts
• glama.json — Glama directory manifest
• Glama listing:

License

Licensed under the Apache License, Version 2.0. Any contribution submittedfor inclusion shall be licensed as above, without additional terms.

Contributing

Contributions are welcome — see the contributing instructions. Thanks toall contributors.

Acknowledgements

Built on the camt053 ISO 20022 Bank Statement library and theModel Context Protocol Python SDK.