pain001-mcp

pain001-mcp

Model Context Protocol server exposing the pain001 ISO 20022 payment library as 17 first-class agent tools.

Contents

Getting started

• What is pain001-mcp? — the problem it solves
• Install — PyPI, virtualenv, Docker
• Quick start — register with Claude Desktop in 30 seconds

Library reference

• Tools — the 17 tools, one resource, one prompt
• Using the tools — call them in-process from Python
• The pain001 suite — core lib, MCP server, LSP server

Operational

• When not to use pain001-mcp — honest boundaries
• Development — gates, make targets
• Security — sandboxing posture
• Documentation — examples, guides
• Contributing — how to get changes in
• License — Apache-2.0

What is pain001-mcp?

The Model Context Protocol (MCP) is an open standard that lets AI agents discover and call external tools in a uniform way. pain001-mcp is the MCP server that turns the pain001 ISO 20022 payment library into 17 first-class agent tools — so an assistant can generate and validate pain.001 Customer Credit Transfer Initiation and pain.008 Customer Direct Debit Initiation messages (the standardised payment instructions behind SEPA and cross-border credit transfers) directly from a conversation.

Every tool is a thin, typed wrapper over the pain001 public API (validators, schema loaders, generate_xml_string, parsers, the version mapper, the ISO 20022 charset sanitiser), so all interfaces behave identically to the CLI, REST API, and in-tree MCP server. Tools return JSON-serialisable data; on a validation error they return an {"error": ...} payload rather than raising.

Concern	How pain001-mcp handles it
Transport	stdio (FastMCP default); zero config beyond the client manifest
Schema fidelity	Tools delegate to pain001's XSD-validated generator
Identifier validation	validate_identifier checks IBAN (ISO 13616 / mod-97) and BIC
Cross-version mapping	migrate_records round-trips data between pain.001.001.03 and .12
Charset compliance	sanitize_to_iso20022_charset transliterates outside-set characters
Message-type aliases	Bare family names pain.001 / pain.008 resolve to pain.001.001.09 / pain.008.001.02
Error surface	Failures return structured {"error": ...}, never tracebacks — listing every missing or invalid field at once

Install

Channel	Command	Notes
PyPI	pip install pain001-mcp	Pulls in pain001 >= 0.0.54 + MCP SDK
Source	git clone https://github.com/sebastienrousseau/pain001-mcp && cd pain001-mcp && poetry install	For development
Docker (GHCR)	docker pull ghcr.io/sebastienrousseau/pain001-mcp:latest	Multi-arch (linux/amd64, linux/arm64); runs pain001-mcp over stdio

Requires Python 3.10 or later. Works on macOS, Linux, and Windows.

Using an isolated virtual environment (recommended)

python -m venv venv
source venv/bin/activate        # macOS/Linux
venv\Scripts\activate           # Windows
python -m pip install -U pain001-mcp

Quick start

Register the server with any MCP client (Claude Desktop shown):

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

That's it. Restart the client and the 17 tools are available to the agent. To check the server starts cleanly before wiring an editor:

pain001-mcp --help
# -> usage: pain001-mcp [-h] ...

The server speaks LSP-style JSON-RPC over stdin/stdout — it is meant to be launched by an MCP client, not used interactively.

Tools

All 17 tools delegate to the pain001 public API, so they behave identically to the CLI and REST API.

• list_message_types — List the supported pain.001 / pain.008 message types
• get_required_fields — Required input fields for a message type
• get_input_schema — Full input JSON Schema for a message type
• inspect_template — Template metadata + accepted formats for a message type
• validate_records — Validate flat records against a message type
• validate_payment_scheme — Run a scheme rulebook (sepa-sct, sepa-sdd, sepa-inst, sepa-b2b, xborder-ct)
• validate_identifier — Validate an IBAN or BIC
• validate_xml_against_schema — Validate an XML payload against its bundled XSD without writing to disk
• generate_message — Generate a validated XML message and return the string
• generate_message_async — Async variant of generate_message for long batches
• generate_message_from_file — Render directly from a CSV path on disk
• list_supported_formats — List the data formats pain001 can load (CSV, SQLite, JSON, JSONL, Parquet)
• parse_camt053 — Parse a camt.053 bank statement XML into structured data
• parse_pain002 — Parse a pain.002 payment-status report XML into structured data
• migrate_records — Migrate flat records between pain.001 schema versions
• sanitize_to_iso20022_charset — Transliterate text to the ISO 20022 Latin set
• convert_mt101 — Convert a legacy SWIFT MT101 (Request for Transfer) into pain.001 records (one per transaction)

Plus one resource and one prompt:

• Resource pain001://schema/{message_type} — Read-only access to the bundled XSD for any supported message type
• Prompt build_payment_batch — Guided multi-step prompt that walks an agent through building a valid batch

First-try ergonomics

The generate path is designed so an agent's first natural call succeeds:

• Records field guide in the tool schema — the records parameter of generate_message / generate_message_async carries a field-by-field guide in its inputSchema description (key fields, accepted aliases, defaults, computed totals), so an agent can build a correct call without a discovery round-trip.
• Message-type aliases — the bare family names pain.001 and pain.008 are accepted wherever a message_type is, resolving to pain.001.001.09 and pain.008.001.02; an invalid type error lists every accepted value.
• validate/generate key coherence — validate_records canonicalizes alias keys (amount, currency, lower-case IBAN/BIC spellings) exactly as generate_message does, so a record that generates cleanly also validates cleanly. Values keep their JSON types; only key names are rewritten.
• Structured, complete error payloads — generation failures return an {"error": ...} payload (never a traceback) that lists every missing or invalid field at once, with row numbers; XSD failures report each violation as element path plus reason (via pain001 >= 0.0.54).
• Computed totals and defaults — nb_of_txs / ctrl_sum are computed from the records and may be omitted; payment_method defaults to TRF and charge_bearer to SLEV. IBAN and BIC values are strictly validated and never coerced.

Using the tools

You can invoke the tools in-process — without a transport — straight through the FastMCP instance. This mirrors what an agent receives over stdio:

import asyncio

from pain001_mcp.server import server

# A single flat payment record satisfying pain.001.001.09.
record = [
    {
        "id": "MSG-0001",
        "date": "2026-01-15T10:30:00",
        "nb_of_txs": 1,
        "ctrl_sum": 100.00,
        "initiator_name": "Acme Embedded Finance Ltd",
        "payment_information_id": "PMT-INFO-0001",
        "payment_method": "TRF",
        "batch_booking": False,
        "service_level_code": "SEPA",
        "requested_execution_date": "2026-01-20",
        "debtor_name": "Acme Embedded Finance Ltd",
        "debtor_account_IBAN": "DE89370400440532013000",
        "debtor_agent_BIC": "DEUTDEFFXXX",
        "charge_bearer": "SLEV",
        "payment_id": "PAY-0001",
        "payment_amount": 100.00,
        "currency": "EUR",
        "creditor_agent_BIC": "NWBKGB2LXXX",
        "creditor_name": "National Westminster Bank",
        "creditor_account_IBAN": "GB29NWBK60161331926819",
        "remittance_information": "Invoice 0001",
    }
]


async def main() -> None:
    async def call(name, args):
        result = await server.call_tool(name, args)
        # mcp 2.x returns a CallToolResult (read .content); 1.x
        # returns the content list, or a (content, meta) tuple.
        content = getattr(result, "content", None)
        if content is None:
            # mcp 2.x returns a CallToolResult (read .content); 1.x
            # returns the content list, or a (content, meta) tuple.
            content = getattr(result, "content", None)
            if content is None:
                content = result[0] if isinstance(result, tuple) else result
        return content[0].text if content else ""

    # 1. Validate an identifier.
    print(await call("validate_identifier",
                     {"kind": "iban", "value": "DE89370400440532013000"}))
    # -> {"kind": "iban", "value": "DE89370400440532013000", "valid": true}

    # 2. Sanitise text to the ISO 20022 Latin set.
    print(await call("sanitize_to_iso20022_charset",
                     {"value": "Café Müller"}))
    # -> {"value": "Café Müller", "sanitised": "Cafe Muller",
    #     "was_valid": false, "changed": true}

    # 3. Generate a validated Customer Credit Transfer Initiation.
    xml = await call("generate_message",
                     {"message_type": "pain.001.001.09", "records": record})
    print(xml[:46])
    # -> <?xml version="1.0" encoding="UTF-8"?>
    #    <Document ...


asyncio.run(main())

The runnable version of this snippet lives in examples/01_mcp_tools.py. See the examples/ folder for a validation pipeline (02_validate_pipeline.py) and a bank-reply parser walkthrough (03_parse_bank_replies.py).

The pain001 suite

pain001-mcp is part of a set of independently installable packages built around the pain001 library — pick whichever ones your stack needs:

Package	Role
pain001	Core library + CLI + FastAPI REST API
pain001-mcp	MCP server for AI agents (this package)
pain001-lsp	Language Server Protocol server for editors

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

When not to use pain001-mcp

• You're not driving an MCP-aware agent. Use the CLI (pain001 …) or the REST API (pain001 serve) directly — both expose the same surface with less indirection.
• You need editor diagnostics, not agent tools. Use pain001-lsp — it speaks the Language Server Protocol to VS Code, Neovim, Helix, Emacs, etc.
• You need to extend the tool surface in-tree. The companion pain001[mcp] extra exposes the same FastMCP instance and is easier to fork inside an organisation's pain001 install.

Development

pain001-mcp uses Poetry and mise.

git clone https://github.com/sebastienrousseau/pain001-mcp.git
cd pain001-mcp
mise install
poetry install

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

Target	What it runs
make check	All gates (REQUIRED before commit)
make test	pytest --cov=pain001_mcp --cov-branch --cov-fail-under=100
make lint	ruff check + black --check
make type-check	mypy --strict
make docs	interrogate --fail-under=100 (docstring coverage)

Current state (v0.0.57): 71 tests passing, 100% line + branch coverage against a 100% enforced floor, mypy --strict clean, interrogate 100%.

Security

• No filesystem writes from tools. generate_message and generate_message_from_file return the XML as a string; no tool writes to disk.
• XML parsing of camt.053 and pain.002 is routed through defusedxml (via the core pain001 library); XXE and entity expansion are rejected.
• Validation failures are returned as structured {"error": ...} payloads — never as stack traces — so the agent never sees an internal path leak.
• Dependencies are pinned via poetry.lock and audited by pip-audit and Bandit in CI.

To report a vulnerability, please use GitHub private vulnerability reporting rather than a public issue.

Documentation

• Runnable examples: examples/
• Release history: CHANGELOG.md
• Core library docs: docs.pain001.com
• MCP specification: modelcontextprotocol.io

Contributing

Contributions are welcome — see the contributing instructions. Thanks to all the contributors who have helped build pain001-mcp.

Related MCP Servers

Part of the ISO 20022 MCP Suite — open-source, Apache-2.0 licensed MCP servers for banking and financial-services AI agents:

Server	Purpose
pacs008-mcp	Generate, validate, parse & scheme-check ISO 20022 pacs.008 FI-to-FI credit transfers + Nov-2026 address linting
camt053-mcp	Parse & reconcile ISO 20022 camt.053 bank-to-customer statements — CBPR+/HVPS+ ready
acmt001-mcp	Generate & validate ISO 20022 acmt account-management messages
bankstatementparser-mcp	Parse bank statements (BAI2, MT940/MT942, CAMT.053, OFX, CSV) into structured transactions
noyalib-mcp	Lossless YAML 1.2 parsing, formatting & validation (Rust, 100% spec compliance)

MCP Registry

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

License

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

pain001.com · PyPI · GitHub