iso20022-mcp: The Unified MCP Gateway for ISO 20022
One Model Context Protocol server, one small set of meta-tools β
search, list_families, describe, validate, generate, parse β that
route across every ISO 20022 message family (pain Β· pacs Β· camt Β·
acmt). Install one thing, discover the whole suite: an agent sees a handful
of verbs instead of the 60+ tools spread across five individual servers.
Latest release: v0.0.4 β 7 routing meta-tools over stdio, light core
(only mcp), backing family servers as optional extras, actionable
structured errors on every validate/generate failure, for Python 3.10+.
The front door to the ISO 20022 MCP Suite.
Why a gateway
The suite has a dedicated, best-in-class server per message family. That depth
is the point β but an agent shouldn't have to know which of five servers and
which of sixty tools it needs before it can act. iso20022-mcp is the thin
routing layer on top: ask it in plain terms ("I need to reconcile a
statement", "generate a credit transfer"), and it points you at β or executes
against β the right family. Small tool surface, whole-suite reach.
The ISO 20022 MCP Suite
iso20022-mcp is the generic message toolkit of eight coordinated,
vendor-neutral MCP servers that together cover the ISO 20022 bank-statement
workflow and the November 2026 structured-address cutover, plus a high-level orchestration layer β readiness scoring, clearing-profile linting, and audit evidence β statement depth,
whole-catalogue routing, reconciliation, multi-format ingestion, and address
remediation. Dependency ranges are kept aligned across the suite,
so the servers co-install cleanly in a single Python environment: start with
one, add the rest as your workflow grows.
| Server | Scope | Surface | Install | Use it when |
|---|
camt053-mcp | ISO 20022 camt.053/camt.052 bank statements: parse, validate, filter, reverse; MT940/MT942 migration; CBPR+ readiness; journal export | 22 MCP tools Β· 4 prompts Β· 3 resources | pip install camt053-mcp | You work with bank-to-customer statements end to end β the suite's flagship |
iso20022-mcp | Unified gateway: search / describe / validate / generate / parse meta-tools routed across the pain Β· pacs Β· camt Β· acmt families | 7 meta-tools | pip install "iso20022-mcp[all]" | You want one entry point to every message family β this package |
reconcile-mcp | Matches expected pain.001 payments against observed camt.053 entries β exact, partial, one-to-many, many-to-one, every match scored and explained | 7 MCP tools | pip install reconcile-mcp | You need explainable statement/payment reconciliation |
bankstatementparser-mcp | Multi-format statement ingestion: ISO 20022 CAMT.053 and pain.001, SWIFT MT940, OFX/QFX, CSV | 5 MCP tools Β· 1 prompt Β· 1 resource | pip install bankstatementparser-mcp | Your statements arrive in mixed or legacy formats |
structured-address-fix-mcp | ISO 20022 postal-address classification, assessment & remediation for the November 2026 structured-address cutover (pacs.008 / pain.001 debtor & creditor addresses) | 9 MCP tools | pip install structured-address-fix-mcp | You need debtor/creditor addresses cliff-ready ahead of 14 Nov 2026 |
iso20022-readiness-suite-mcp | Orchestration gateway: detect β structurally validate β clearing-profile lint β readiness score, plus automated remediation and pacs.002 bank-response simulation β a meta-client over the foundational servers | 4 MCP tools | pip install iso20022-readiness-suite-mcp | You want one high-level readiness / orchestration entry point over the suite |
iso20022-bank-profile-mcp | Manages, validates and serves bank-specific clearing profiles / rule packs (CBPR+, SEPA_Instant, FedNow, Generic); premium rule-pack entitlement gating | 4 MCP tools | pip install iso20022-bank-profile-mcp | You lint payments against your own institution's market practice |
iso20022-evidence-pack-mcp | Compiles readiness findings, remediation diffs and simulated responses into a sealed, Ed25519-signable audit evidence pack | 6 MCP tools | pip install iso20022-evidence-pack-mcp | You need tamper-evident audit / certification artifacts |
In one line each: camt053-mcp is the bank-statement flagship (deepest
camt.05x surface, stdio + authenticated streamable HTTP);
iso20022-mcp is the generic message toolkit (a handful of verbs over
the whole catalogue); reconcile-mcp is the reconciliation workflow
(did the money we expected actually arrive?);
bankstatementparser-mcp is the ingestion layer (many formats in, one
transaction shape out); and structured-address-fix-mcp is the
postal-address specialist (debtor/creditor addresses cliff-ready for the
Nov 2026 cutover).
The gateway also routes to the per-family servers β
pain001-mcp, pacs008-mcp,
acmt001-mcp, and camt-exceptions β
installed as extras (see Routing).
Install
The core is light. Add the families you need as extras (or [all]):
pip install "iso20022-mcp[all]"
pip install "iso20022-mcp[pacs,camt]"
pip install iso20022-mcp
uvx --from "iso20022-mcp[all]" iso20022-mcp
MCP client config (e.g. Claude Desktop):
{
"mcpServers": {
"iso20022": {
"command": "iso20022-mcp"
}
}
}
The 7 routing meta-tools:
search β Find message types by use-case / keyword ("reconciliation", "pacs.008"). (families: all β catalogue)
list_families β List families, their capabilities, and which backing packages are installed. (families: all)
list_servers β Full suite map: families + E&I messages + specialized servers (reconcile, agent-payment bridge). (families: all)
describe β Required fields + input JSON Schema for a message type. (families: all)
validate β Validate records against a message type's schema. (families: all)
generate β Generate a validated ISO 20022 XML message from records. (families: pain Β· pacs Β· acmt)
parse β Parse an inbound ISO 20022 XML message into structured data. (families: pacs Β· camt)
Operations are capability-aware: generate on a camt.053 statement (an
inbound format) returns a clear, explanatory error rather than failing
obscurely, and every "package not installed" case tells you exactly what to
pip install.
Three ergonomics guarantees hold across the routed families:
- Actionable structured errors. Any error a backing server raises β
not just the ones it returns β reaches the agent as an
{"error": "<Type>: <message>"} payload instead of an opaque
tool-execution failure. For pain generation the error lists every
missing or invalid field at once, so one fix-and-retry suffices.
- Family aliases for
message_type. Bare family names resolve to a
concrete version via the backing server: pain.001 β
pain.001.001.09, pain.008 β pain.008.001.02. Fully-versioned
types are still preferred where you know them.
- Per-family parse coverage, stated up front.
parse covers the
inbound families only: pacs (e.g. pacs.008) and camt (e.g.
camt.053). The initiation families pain and acmt are
outbound-only β they have no parser here, so don't attempt a
generateβparse round-trip for pain.001 or acmt.001; use validate
(or the backing server's XSD validation) instead.
Routing
| Prefix | Family | Backing server | generate | parse |
|---|
pain | Customer Credit Transfer Initiation | pain001-mcp | β
| β |
pacs | FI-to-FI Customer Credit Transfer | pacs008-mcp | β
| β
|
camt | Bank-to-Customer Statement | camt053-mcp | β | β
|
acmt | Account Opening Instruction | acmt001-mcp | β
| β |
camt.056/camt.029 | Cancellation / Resolution (E&I) | camt-exceptions | β
| β |
generate("camt.056.001.12", β¦) routes to camt-exceptions. The gateway also
surfaces the specialized servers β reconcile-mcp and
ap2-iso20022 β via search and list_servers for discovery
(they're invoked through their own tools).
The gateway imports each backing server lazily and optionally β the core
depends only on mcp, and a family's server is loaded on first use. Message
types are matched on their prefix (pacs.008.001.08 β pacs). The pain
extra requires pain001-mcp >= 0.0.56, the release that carries the
LLM-ergonomic generate surface (field aliases, computed nb_of_txs /
ctrl_sum, all-at-once field errors) the gateway's guarantees build on.
Example
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
For the dedicated reconciliation engine that matches camt.053 statements
against expected pain.001 payments, see reconcile-mcp.
Development
git clone https://github.com/sebastienrousseau/iso20022-mcp
cd iso20022-mcp
python -m venv .venv && . .venv/bin/activate
pip install -e . && pip install pytest pytest-cov ruff black mypy
pytest
ruff check iso20022_mcp tests && black --check iso20022_mcp tests && mypy iso20022_mcp
Licence
Licensed under the Apache License, Version 2.0.
mcp-name: io.github.sebastienrousseau/iso20022-mcp