pacs008-mcp: An MCP Server for ISO 20022 FI-to-FI Credit Transfers

pacs008-mcp banner

Build Registry Docs OpenSSF Scorecard OpenSSF Best Practices License: Apache-2.0 OR MIT Python 3.11 or newer Glama MCP server listing

pacs008-mcp Demo

A Model Context Protocol server that exposes the pacs008 ISO 20022 FI-to-FI Customer Credit Transfer library as tools for AI agents and assistants — discover message types and scheme profiles, validate records against the JSON Schema and against a rail’s usage guidelines, generate validated XML, validate raw XML against the bundled XSD, and parse inbound messages, all from your favourite MCP client.

Latest release: v0.0.16: 16 MCP tools over stdio, streamable HTTP or SSE, all backed by the pacs008 library, for Python 3.11+ (3.10 is no longer supported). The release SBOMs now describe the runtime set the image ships, not the build tooling.

Contents

Overview

The Model Context Protocol (MCP) is an open standard that lets AI agents and assistants discover and call external tools in a uniform way. pacs008-mcp is an MCP server that turns the pacs008 library into a set of first-class agent tools, so an assistant can generate, validate, and parse ISO 20022 pacs.008 FI-to-FI Customer Credit Transfer XML messages — and the related pacs.002/.004 status and return messages — directly from a conversation.

Every tool is a thin, typed wrapper over the pacs008 library — the same package used by the CLI and REST API — so all interfaces behave identically. Tools return JSON-serialisable data; on a validation error they return an {"error": ...} payload rather than raising.

flowchart LR
    A["MCP client<br/>(Claude Desktop, IDE, agent)"] -->|stdio| B["pacs008-mcp"]
    B -->|delegates to| C["pacs008 library"]
    C -->|render + validate| D["ISO 20022 pacs XML"]

Install

pacs008-mcp runs on macOS, Linux, and Windows and requires Python 3.11+ and pip. It pulls in the core pacs008 library and the MCP SDK automatically.

python -m pip install pacs008-mcp

Note: while the core pacs008 library is not yet on PyPI, install it from source first:

python -m pip install "git+https://github.com/sebastienrousseau/pacs008.git"
python -m pip install pacs008-mcp

Quick Start

Launch the server over stdio (the default transport):

pacs008-mcp

Register it with any MCP client (e.g. Claude Desktop) by adding it to the client’s configuration:

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

Transports

One command line, three transports:

Command

Transport

Endpoint

Protocol revisions

pacs008-mcp

stdio

the client spawns the process

2026-07-28, 2025-11-25

pacs008-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

pacs008-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 in both protocol eras and over SSE with the MCP SDK client; see ADR 0001.

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

Tools

All tools wrap the pacs008 library, so they behave identically to the CLI and REST API.

  • list_message_types — List the 20 supported ISO 20022 pacs message types

  • list_schemes — List the registered scheme / usage-guideline profiles

  • get_scheme — Inspect a scheme profile’s rules

  • get_required_fields — Required input fields for a message type

  • get_input_schema — Full input JSON Schema for a message type

  • validate_records — Validate flat records against a message type’s schema

  • validate_scheme — Validate records against a scheme’s usage guidelines

  • generate_message — Generate a validated pacs XML message

  • validate_xml — Validate a raw XML string against the bundled XSD

  • parse_message — Parse & classify an inbound ISO 20022 message

  • convert_mt103 — Convert a legacy SWIFT MT103 into pacs.008-ready records (MT→MX migration)

  • classify_address — Classify a postal address as structured / hybrid / unstructured

  • validate_address — Validate one postal address against an address policy

  • repair_address — Upgrade legacy unstructured address lines toward hybrid/structured form

  • validate_addresses — Batch-validate every party address across payment rows

  • verify_bic_online — Check a BIC’s format and look it up in a configured BIC directory (needs the online extra)

November 2026 structured-address cliff

On 14 November 2026, fully unstructured postal addresses are decommissioned across SWIFT CBPR+, HVPS+, TARGET2 RTGS, CHAPS, Fedwire and Lynx — after that date, any cross-border or high-value payment carrying an unstructured-only postal address is rejected at the rail. The four address tools above wrap the pacs008 library’s standards.address module so an agent can get ahead of the deadline: classify_address shows where an address stands, validate_address / validate_addresses enforce a policy (defaulting to the cliff rule hybrid_or_structured, which rejects unstructured addresses), and repair_address runs country-aware heuristics (GB, US, DE, FR, JP, plus a best-effort fallback) to lift legacy address lines into hybrid form. The repair step is experimental — audit its output before submitting downstream.

Using the tools

You can invoke the tools in-process — without a transport — straight through the server instance. This mirrors what an agent receives over stdio. The runnable version of this snippet lives in examples/mcp_tools.py.

import asyncio

from pacs008_mcp.server import server

record = [
    {
        "msg_id": "MSG001",
        "creation_date_time": "2026-01-15T10:30:00",
        "nb_of_txs": "1",
        "settlement_method": "CLRG",
        "interbank_settlement_date": "2026-01-15",
        "end_to_end_id": "E2E001",
        "interbank_settlement_amount": "1000.00",
        "interbank_settlement_currency": "EUR",
        "charge_bearer": "SHAR",
        "debtor_name": "Debtor Corp",
        "debtor_agent_bic": "DEUTDEFF",
        "creditor_agent_bic": "COBADEFF",
        "creditor_name": "Creditor Ltd",
    }
]


async def main() -> None:
    async def call(name, args):
        result = await server.call_tool(name, args)
        content = result[0] if isinstance(result, tuple) else result
        return content[0].text if content else ""

    print(await call("list_schemes", {}))
    xml = await call("generate_message",
                     {"message_type": "pacs.008.001.08", "records": record})
    print(xml[:46])  # -> <?xml version="1.0" encoding="UTF-8"?> ...


asyncio.run(main())

Run it directly:

python examples/mcp_tools.py

Development

pacs008-mcp uses Poetry and mise.

git clone https://github.com/sebastienrousseau/pacs008-mcp.git && cd pacs008-mcp
mise install
poetry install
poetry shell

This package depends on the core pacs008 library. Until it is on PyPI, install it from source first: pip install "git+https://github.com/sebastienrousseau/pacs008.git".

A Makefile orchestrates the quality gates (kept in lockstep with CI):

make check        # all gates (REQUIRED before commit)
make test         # pytest, 100% line+branch coverage
make lint         # ruff + black
make type-check   # mypy --strict
make doc-coverage # interrogate, 100% docstrings
make mutate       # mutmut over the tool handlers, gated
make docs         # Sphinx site, warnings are errors

Documentation

MCP Registry

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

License

Licensed under the Apache License, Version 2.0. Any contribution submitted for inclusion shall be licensed as above, without additional terms.

Contribution

Contributions are welcome — see the contributing instructions. Thanks to all contributors.

Acknowledgements

Built on the pacs008 ISO 20022 FI-to-FI Customer Credit Transfer library and the Model Context Protocol Python SDK.