[iso20022-mcp logo]
iso20022-mcp
One MCP server with seven meta-tools that route across every ISO 20022 message family.
[Build]
[Registry]
[Docs]
[OpenSSF Scorecard]
[License: Apache-2.0 OR MIT]
[Python 3.10 or newer]
[OpenSSF Best Practices]
[Glama MCP score]
[iso20022-mcp demo: the command-line help, then list_families showing each family and whether its server is installed]
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
Library reference
Operational
Install
As a Python library
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:
MCP client config (e.g. Claude Desktop):
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
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.
Capabilities at a glance
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:
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.
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
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:
--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.
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
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:
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
