iso20022-mcp

iso20022-mcp

One MCP server with seven meta-tools that route across every ISO 20022 message family.

---

Contents

Getting started

• Install — pip extras per family, uvx, MCP client config
• Requirements — toolchain floor, platforms
• Quick Start — search, describe, validate, generate and parse from one server

The iso20022-mcp ecosystem

• The iso20022-mcp ecosystem — the ISO 20022 MCP Suite and the family servers this gateway routes to

Library reference

• Capabilities at a glance — the current surface by theme
• Ecosystem comparison — short matrix; full table at docs/COMPARISON.md
• Benchmarks — headline numbers; full table at docs/BENCHMARKS.md
• Features — module-level capability list
• Configuration — core options
• Examples — runnable example index

Operational

• When not to use iso20022-mcp — limitations
• Development — make targets, fuzzing, CI
• Security — guarantees and compliance
• Documentation — all reference docs
• Stability guarantees — SemVer axis, output stability, minimum toolchain discipline
• License

---

Install

As a Python library

pip install "iso20022-mcp[all]"

Latest release: v0.0.18: 7 routing meta-tools over stdio, streamable HTTP or SSE (optionally over HTTPS), light core (only mcp), backing family servers as optional extras, actionable structured errors on every validate/generate failure, for Python 3.10+.

The core is light. Add the families you need as extras:

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

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

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

---

Requirements

• Python 3.10 or newer, tested in CI on 3.10, 3.11, 3.12, 3.13 and 3.14 on Linux (toolchain policy).
• mcp 1.30 or newer on the 1.x line, or 2.2 or newer on the 2.x line. Releases affected by GHSA-84m7-p3x7-pcfv cannot be resolved.
• The family servers are optional extras: pain, pacs, camt, acmt, or all.

---

Quick Start

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

Start with search or list_families to find a message type, describe it for its required fields and input schema, then validate, generate or parse. Each call is routed to the family server for that message type's prefix.

---

The iso20022-mcp ecosystem

iso20022-mcp is the generic message toolkit of the ISO 20022 MCP Suite: eight coordinated, vendor-neutral MCP servers that cover the ISO 20022 bank-statement workflow and the November 2026 structured-address cutover, plus an orchestration layer for readiness scoring, clearing-profile linting and audit evidence. Dependency ranges are kept aligned across the suite, so the servers co-install cleanly in one Python environment: start with one, add the rest as your workflow grows.

Component	Purpose	Use case
camt053-mcp	ISO 20022 camt.053/camt.052 bank statements: parse, validate, filter, reverse; MT940/MT942 migration; CBPR+ readiness; journal export (24 tools, 4 prompts, 3 resources)	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)	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 tools)	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 tools, 1 prompt, 1 resource)	Your statements arrive in mixed or legacy formats
structured-address-fix-mcp	ISO 20022 postal-address classification, assessment and remediation for the November 2026 structured-address cutover (9 tools)	You need debtor/creditor addresses ready before 14 Nov 2026
iso20022-readiness-suite-mcp	Orchestration: detect, validate, clearing-profile lint and readiness score, plus remediation and pacs.002 response simulation (4 tools)	You want one high-level readiness entry point over the suite
iso20022-bank-profile-mcp	Manages, validates and serves bank clearing profiles and rule packs (CBPR+, SEPA_Instant, FedNow, Generic) (4 tools)	You lint payments against your institution's market practice
iso20022-evidence-pack-mcp	Compiles findings, remediation diffs and simulated responses into a sealed, Ed25519-signable audit evidence pack (6 tools)	You need tamper-evident audit or certification artifacts
pain001-mcp, pacs008-mcp, acmt001-mcp, camt-exceptions	The per-family servers this gateway routes to, installed as extras	Installed for you by iso20022-mcp[all]; see Features

---

Capabilities at a glance

Area	Capability	Status
Discovery	search, list_families, list_servers over the whole catalogue	Released; works with the core install
Schemas	describe returns required fields and the input JSON Schema	Released; needs the family's extra
Validation	validate checks records against a message type's schema	Released; every family
Generation	generate builds validated XML for pain, pacs, acmt and camt.056/camt.029	Released
Parsing	parse reads inbound pacs and camt XML	Released; pain and acmt are outbound-only
Transports	stdio, streamable HTTP and SSE, with optional HTTPS	Released; HTTPS since 0.0.18

---

Ecosystem comparison

The alternative to this gateway is connecting an agent to each family server directly. Measured over stdio with list_tools on 2026-10-20:

Project	Servers to configure	Tools the agent sees	Estimated catalogue tokens
iso20022-mcp	1	7	~2,200
All four family servers directly	4	73	~36,400

See docs/COMPARISON.md for the evidence and complete matrix.

---

Benchmarks

Routing costs microseconds; the first call into a family pays its lazy import once per process. Measured with benches/bench_gateway.py --quick.

Scenario	Result	Environment
family_for routing	0.54 µs	Apple A18 Pro, Python 3.12.15, mcp 2.3.0
search_catalog	7.29 µs	Apple A18 Pro, Python 3.12.15, mcp 2.3.0
First pain.001 call (cold import)	528 ms	Apple A18 Pro, Python 3.12.15, fresh interpreter
Later pain.001 call (warm)	5.04 µs	Apple A18 Pro, Python 3.12.15

See docs/BENCHMARKS.md for methodology and full results.

---

Features

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.

---

Configuration

One command line, three transports:

Command	Transport	Endpoint	Protocol revisions
iso20022-mcp	stdio	the client spawns the process	2026-07-28, 2025-11-25
iso20022-mcp --transport streamable-http	Streamable HTTP	http://127.0.0.1:8000/mcp	2026-07-28 (stateless, server/discover) and 2025-11-25 (initialize, Mcp-Session-Id) on the same endpoint; responses stream as server-sent events, GET opens the server-to-client stream
iso20022-mcp --transport sse	HTTP+SSE (2024-11-05)	http://127.0.0.1:8000/sse and /messages/	for clients that still expect the older transport

--host and --port change the bind address (defaults 127.0.0.1 and 8000). --ssl-certfile cert.pem --ssl-keyfile key.pem serves either HTTP transport over HTTPS instead, on mcp 1.x and 2.x alike. The HTTP transports carry no authentication of their own: bind loopback, or put the server behind a gateway you trust before binding a routable address. Every release is verified over streamable HTTP with passmcp in both protocol eras and over SSE with the MCP SDK client; see ADR 0001.

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

Run iso20022-mcp --help for every option.

---

Examples

• examples/mcp_tools.py: discovery with the core install, then routed describe, validate, generate and parse calls (python examples/mcp_tools.py after pip install -e ".[all]").
• benches/bench_gateway.py: what the gateway adds on top of each family server.
• For the dedicated engine that matches camt.053 statements against expected pain.001 payments, see reconcile-mcp.

---

When not to use iso20022-mcp

• You need a family's specialist tools. The gateway exposes the operations every family shares. camt053-mcp's MT940 migration or journal export, for example, are only on that server: connect it directly.
• You need to round-trip pain or acmt. They are outbound-only here, with no parser.
• You need a bank, a settlement engine or a payment approver. This routes and validates messages; it sends nothing anywhere and is not bank certification.
• You need authentication on the HTTP transports. There is none built in; put an authenticating gateway in front.

---

Development

git clone https://github.com/sebastienrousseau/iso20022-mcp
cd iso20022-mcp
python -m venv .venv && . .venv/bin/activate
make dev
make check                         # lint, mypy strict, tests, version agreement
python benches/bench_gateway.py --quick

make check runs ruff, black, mypy in strict mode, pytest with a 100% line and branch coverage gate (backends faked), and the version-agreement check. CI also runs CodeQL, OpenSSF Scorecard, reuse lint, the MCP Inspector, Hypothesis property tests, and Atheris fuzzing of every tool (two minutes per change, 30 minutes weekly). See DEVELOPMENT.md and CONTRIBUTING.md.

---

Security

Tools are read-only, idempotent and closed-world: no tool opens a path, a URL or a socket, and every call is routed through one registry table, so no caller input reaches an import. Stdio is the default; the HTTP transports bind loopback, can serve HTTPS, and carry no authentication of their own. Releases are built reproducibly from a signed tag, with SLSA provenance and sigstore signatures you can verify. The threat model and evidence are in the assurance case and the security review. The project holds the OpenSSF Best Practices passing badge.

Report vulnerabilities according to SECURITY.md.

---

Documentation

User manual · API reference: the tools · Developer guide · Architecture · Family map · Changelog · Roadmap

---

Stability guarantees

The project is pre-1.0 and versions advance in 0.0.1 steps. The breaking axis is the MCP surface an agent sees: tool names, their arguments, and the shape of what they return, including the {"error": ...} payload. A change to any of these is breaking even when no Python signature moves, and is called out in the changelog. Generated XML comes from the family servers and follows their own stability rules. The Python floor moves only as described in the toolchain policy.

---

License

This project is dual-licensed under either:

• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option. Dependencies keep their own licences.

The logo is "Computer connected" by glyph.faisalovers from Noun Project, licensed under CC BY 3.0 and recoloured for light and dark themes.

---

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