pain001-mcp: The MCP Server for ISO 20022 Payments

pain001-mcp v0.0.57 exposes the Pain001 suite to AI agents as 17 Model Context Protocol tools. Claude Desktop, Claude Code, Cursor, and any MCP-compatible orchestrator can validate IBANs, migrate message versions, convert SWIFT MT101, and generate schema-validated pain.001 XML — inside a conversation, on your own machine.

Card networks and PSPs have built agentic checkout rails. The corporate payment-file layer — where credit transfers are actually initiated — had no agent interface. This server fills that gap. Payment data never leaves your machine: the transport is stdio, and every tool is annotated read-only and idempotent, so an agent can explore safely without side effects.

01. The 17 tools#

Tool	What it does
`list_message_types`	List the 11 supported message definitions with human-readable names.
`get_required_fields`	Return the required input fields for a message type.
`get_input_schema`	Return the full JSON Schema for a message type.
`validate_records`	Validate flat payment records against the input schema.
`validate_identifier`	Check a single IBAN (ISO 13616 mod-97) or BIC (ISO 9362).
`generate_message`	Generate XSD-validated pain XML from in-memory records.
`generate_message_async`	Off-event-loop generation for large batches.
`generate_message_from_file`	Generate XML from a CSV file on disk.
`list_supported_formats`	List loadable on-disk formats (CSV, SQLite, JSON, JSONL, Parquet).
`parse_camt053`	Parse a camt.053 bank statement XML file.
`parse_pain002`	Parse a pain.002 payment status report.
`inspect_template`	Show the CSV column headers of a bundled template.
`validate_payment_scheme`	Enforce a scheme rulebook: SEPA SCT, Instant, SDD Core, B2B, or cross-border.
`migrate_records`	Migrate records between pain.001 versions (e.g. `.03` → `.09`).
`validate_xml_against_schema`	Validate raw XML against the bundled official XSD.
`sanitize_to_iso20022_charset`	Transliterate text to the ISO 20022 Latin character set.
`convert_mt101`	Convert a legacy SWIFT MT101 message into pain.001 records.

The server also publishes a pain001://schema/{message_type} resource and a build_payment_batch prompt. Shorthand aliases resolve sensibly: pain.001 → pain.001.001.09, pain.008 → pain.008.001.02.

02. Registration#

pip install pain001-mcp

Claude Desktop (claude_desktop_config.json):

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

Claude Code:

claude mcp add pain001 -- pain001-mcp

A Docker image is published as ghcr.io/sebastienrousseau/pain001-mcp with build provenance attestation, and the server is listed in the MCP registry as io.github.sebastienrousseau/pain001-mcp.

03. Design decisions that matter in a payments context#

Read-only by contract. All 17 tools carry MCP ToolAnnotations with readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The server never writes to your filesystem.
Errors are data, not crashes. Tools return structured {"error": ...} payloads instead of raising, so agent loops degrade gracefully.
Local-only transport. stdio only — no network listener, no credentials, no payment data leaving the host.
Validated output or nothing. generate_message runs the same JSON Schema → scheme rulebook → XSD pipeline as the CLI; an agent cannot produce a malformed file.

Note the distinction: pain001 mcp (the core library's built-in server) exposes a minimal 5-tool surface. The full 17-tool surface documented here is the standalone pain001-mcp package.

FAQ#

Can an AI agent actually submit payments with this?

No. The server generates and validates payment files; it has no bank connectivity and no tool with side effects beyond returning XML as text. Submission to your bank channel remains a human-controlled step — by design.

Does it work with agentic-payment protocols like AP2?

It complements them. AP2 and similar protocols handle mandates and authorisation for agent-initiated commerce; pain001-mcp handles the ISO 20022 file layer that corporate banking channels actually consume. The related ap2-iso20022 project bridges the two.

Which clients are tested?

Any MCP client speaking stdio works. Claude Desktop, Claude Code, and Cursor configurations are documented in the repository, and CI runs the official MCP Inspector against every release.