iso20022-mcp

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

Related MCP server: pain001-mcp

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.

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.

{
  "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