pain001-mcp

Model Context Protocol server exposing the pain001 ISO 20022 payment library as 16 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 16 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.

Install

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

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.

Plus one resource and one prompt:

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

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

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

Security

• No filesystem writes from tools. generate_message returns the XML as a string; only generate_payment_file writes, and only to a caller-supplied path.
• 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:

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