iso20022-mcp

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

Tools

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                      # 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