io.github.sebastienrousseau/iso20022-mcp
Unified ISO 20022 MCP gateway routing across the pain, pacs, camt and acmt message families.
Open source Open in the app JSON README (API)
About
Unified ISO 20022 MCP gateway routing across the pain, pacs, camt and acmt message families.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- sebastienrousseau
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.0.11
- Stars
- 1
- Last push
- 2026-08-29T22:05:18Z
- Repository state
- ativo
- Language
- Python
- License
- NOASSERTION
- Added
- 2026-08-29 04:01:22
- Updated
- 2026-08-29 23:00:12
- Origin id
io.github.sebastienrousseau/iso20022-mcp
README
# iso20022-mcp: The Unified MCP Gateway for ISO 20022
**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.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](#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 | 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`](#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"
}
}
}
```
## 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`][pain001-mcp] | ✅ | — |
| `pacs` | FI-to-FI Customer Credit Transfer | [`pacs008-mcp`][pacs008-mcp] | ✅ | ✅ |
| `camt` | Bank-to-Customer Statement | [`camt053-mcp`][camt053-mcp] | — | ✅ |
| `acmt` | Account Opening Instruction | [`acmt001-mcp`][acmt001-mcp] | ✅ | — |
| `camt.056`/`camt.029` | Cancellation / Resolution (E&I) | [`camt-exceptions`][camt-exceptions] | ✅ | — |
`generate("camt.056.001.12", …)` routes to `camt-exceptions`. The gateway also
surfaces the specialized servers — [`reconcile-mcp`][reconcile-mcp] and
[`ap2-iso20022`][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`][reconcile-mcp].
## Development
```sh
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](LICENSE).
---
`mcp-name: io.github.sebastienrousseau/iso20022-mcp`
[mcp]: https://modelcontextprotocol.io
[pain001-mcp]: https://github.com/sebastienrousseau/pain001-mcp
[pacs008-mcp]: https://github.com/sebastienrousseau/pacs008-mcp
[camt053-mcp]: https://github.com/sebastienrousseau/camt053-mcp
[acmt001-mcp]: https://github.com/sebastienrousseau/acmt001-mcp
[reconcile-mcp]: https://github.com/sebastienrousseau/reconcile-mcp
[bsp-mcp]: https://github.com/sebastienrousseau/bankstatementparser-mcp
[saf-mcp]: https://github.com/sebastienrousseau/structured-address-fix-mcp
[camt-exceptions]: https://github.com/sebastienrousseau/camt-exceptions
[ap2-iso20022]: https://github.com/sebastienrousseau/ap2-iso20022