iso20022-mcp

<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->

# iso20022-mcp: The Unified MCP Gateway for ISO 20022

<p align="center">
  <a href="https://github.com/sebastienrousseau/iso20022-mcp/actions"><img src="https://github.com/sebastienrousseau/iso20022-mcp/workflows/ci/badge.svg?style=for-the-badge&logo=github" alt="Build" /></a>
  <a href="https://pypi.org/project/iso20022-mcp/"><img src="https://img.shields.io/pypi/v/iso20022-mcp.svg?style=for-the-badge&color=fc8d62&logo=pypi" alt="PyPI" /></a>
  <a href="https://glama.ai/mcp/servers/sebastienrousseau/iso20022-mcp"><img src="https://glama.ai/mcp/servers/sebastienrousseau/iso20022-mcp/badges/score.svg?style=for-the-badge" alt="Glama MCP score" /></a>
  <a href="https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/iso20022-mcp"><img src="https://img.shields.io/ossf-scorecard/github.com/sebastienrousseau/iso20022-mcp?style=for-the-badge&label=OpenSSF%20Scorecard&logo=openssf" alt="OpenSSF Scorecard" /></a>
  <a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-Apache--2.0%20OR%20MIT-blue.svg?style=for-the-badge" alt="License: Apache-2.0 OR MIT" /></a>
  <a href="https://github.com/sebastienrousseau/iso20022-mcp/blob/main/docs/POLICIES.md"><img src="https://img.shields.io/badge/python-%3E%3D3.10-93450a.svg?style=for-the-badge&logo=python" alt="Python 3.10+" /></a>
</p>

<p align="center">
  <img src=".github/demo.gif" alt="iso20022-mcp Demo" width="100%" />
</p>


**One [Model Context Protocol][mcp] 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.13**: 7 routing meta-tools over stdio, streamable
> HTTP or SSE, 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](#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`][camt053-mcp] | ISO 20022 `camt.053`/`camt.052` bank statements: parse, validate, filter, reverse; MT940/MT942 migration; CBPR+ readiness; journal export | 24 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`](#install) | 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`][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`][bsp-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`][saf-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`](https://github.com/sebastienrousseau/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`](https://github.com/sebastienrousseau/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`](https://github.com/sebastienrousseau/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`][pain001-mcp], [`pacs008-mcp`][pacs008-mcp],
[`acmt001-mcp`][acmt001-mcp], and [`camt-exceptions`][camt-exceptions] —
installed as extras (see [Routing](#routing)).

## Install

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

```sh
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):

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

## Transports

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`). 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](https://github.com/sebastienrousseau/passmcp) in both protocol
eras and over SSE with the MCP SDK client; see
[ADR 0001](docs/adr/0001-three-transports-one-command-line.md).

```json
{
  "mcpServers": {
    "iso20022": { "url": "http://127.0.0.1:8000/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 `