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.2 — 7 routing meta-tools over stdio, light core (only mcp), backing family servers as optional extras, 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.

Install

The core is light. Add the families you need as extras (or [all]):

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

MCP client config (e.g. Claude Desktop):

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

The meta-tools

Tool	What it does	Families
search	Find message types by use-case / keyword ("reconciliation", "pacs.008").	all (catalogue)
list_families	List families, their capabilities, and which backing packages are installed.	all
list_servers	Full suite map: families + E&I messages + specialized servers (reconcile, agent-payment bridge).	all
describe	Required fields + input JSON Schema for a message type.	all
validate	Validate records against a message type's schema.	all
generate	Generate a validated ISO 20022 XML message from records.	pain · pacs · acmt
parse	Parse an inbound ISO 20022 XML message into structured data.	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.

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).

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=[…])   # → validated XML
parse(message_type="camt.053", xml="<Document>…")

For the dedicated reconciliation engine that matches camt.053 statements against expected pain.001 payments, see reconcile-mcp.

The suite

iso20022-mcp is the front door to a family of vendor-neutral, Python-native ISO 20022 MCP servers:

• pain001-mcp — customer credit transfer initiation.
• pacs008-mcp — FI-to-FI credit transfers.
• camt053-mcp — bank-to-customer statements.
• acmt001-mcp — account opening instructions.
• reconcile-mcp — explainable statement/payment reconciliation.
• bankstatementparser-mcp — MT94x / BAI2 / OFX parsing.

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                      # 100% branch coverage gate (backends faked)
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