iso20022-bank-profile-mcp: The ISO 20022 Bank Clearing-Profile Server

[![PyPI Version][pypi-badge]][07] [![Python Versions][python-versions-badge]][07] [![License][license-badge]][01] [![Tests][tests-badge]][tests-url] [![Quality][quality-badge]][quality-url] [![OpenSSF Scorecard][scorecard-badge]][scorecard-url] [![Documentation][docs-badge]][docs-url]

A fully local, closed-world [Model Context Protocol][mcp] server that manages, validates, and serves bank-specific ISO 20022 clearing profiles / rule packs — the market-practice rules that sit beyond structural XSD validation. It is a foundational member of the ISO 20022 MCP Suite and a sibling of iso20022-readiness-suite-mcp, whose readiness gateway can consume the profiles this server serves.

The November 2026 milestones. As the major schemes (CBPR+, HVPS+, T2, FedNow) tighten their ISO 20022 requirements — structured postal addresses chief among them — a payment that was fine yesterday can be rejected tomorrow. iso20022-bank-profile-mcp turns those scheme rules into versioned, agent-callable clearing profiles: list_profiles and get_profile serve them, lint_payload evaluates a payload against one, and validate_profile_definition vets a bank-supplied rule pack. v0.0.2, stdio by default (plus an optional OAuth 2.1 HTTP transport), 4 read-only tools, premium rule-pack entitlement gating, Python 3.10+.

Contents

• Overview
• The ISO 20022 MCP Suite
• Install
• Quick Start
• Tools
• HTTP transport & authentication
• How it fits the suite
• Open-core vs premium
• When not to use iso20022-bank-profile-mcp
• Development
• Security
• Documentation
• License
• Contributing
• Acknowledgements

Overview

The [Model Context Protocol][mcp] (MCP) is an open standard that lets AI agents and assistants discover and call external tools in a uniform way. iso20022-bank-profile-mcp owns the market-practice profile layer of the ISO 20022 MCP Suite: the scheme-specific and bank-specific rules a payment must satisfy to clear, which live above the XSD and vary by clearing system.

A clearing profile is pure data — a profile_id, its market_practice, the messages it supports, and a list of declarative custom_rules. The server ships open baseline profiles (Generic, CBPR+, SEPA_Instant, FedNow) and exposes four read-only tools to discover them, fetch them in full, lint a payload against one, and validate a candidate rule pack.

It is a fully local, closed-world server: no network surface, no sub-servers, no meta-client. Every tool computes from the bundled profile data and returns typed, JSON-serialisable output; on any failure — a bad input, an unparseable payload, an unknown profile — it returns an {"error": ...} payload rather than raising into the client transport. XML payloads are parsed with defusedxml only (no XXE / billion-laughs).

• Website: https://sebastienrousseau.github.io/iso20022-bank-profile-mcp/
• Source code: https://github.com/sebastienrousseau/iso20022-bank-profile-mcp
• Bug reports: https://github.com/sebastienrousseau/iso20022-bank-profile-mcp/issues

flowchart TD
    A["MCP client<br/>(Claude Desktop, IDE, agent)"] -->|stdio| B["iso20022-bank-profile-mcp<br/>(clearing-profile server)"]
    B --> C["ProfileEngine<br/>(bundled JSON + register() seam)"]
    C --> D["Generic"]
    C --> E["CBPR+"]
    C --> F["SEPA_Instant"]
    C --> G["FedNow"]
    H["iso20022-readiness-suite-mcp<br/>(readiness gateway)"] -.consumes profiles.-> B

The ISO 20022 MCP Suite

iso20022-bank-profile-mcp is one of a set of coordinated, vendor-neutral MCP servers for the ISO 20022 migration. Dependency ranges are kept aligned across the suite, so the servers co-install cleanly in a single Python environment.

Where the foundational servers each do one message job well and the readiness gateway composes them, this server owns the clearing profiles: it manages, validates, and serves the market-practice rule packs the rest of the suite lints against.

Install

iso20022-bank-profile-mcp runs on macOS, Linux, and Windows and requires Python 3.10+ and pip. It pulls in the MCP SDK, pydantic, and defusedxml automatically — all published on PyPI.

python -m pip install iso20022-bank-profile-mcp

Or run it without installing, straight from PyPI, with uvx:

uvx iso20022-bank-profile-mcp

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

Quick Start

For the 10-minute install → MCP client config → first conversation tutorial, see docs/quickstart.md.

Launch the server over stdio (the FastMCP default transport):

iso20022-bank-profile-mcp

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

{
  "mcpServers": {
    "iso20022-bank-profile": { "command": "iso20022-bank-profile-mcp" }
  }
}

The command speaks MCP on stdin/stdout — it is meant to be launched by an MCP client, not used interactively. The agent can then call the tools below.

You can also invoke the tools in-process — without a transport — straight through the FastMCP instance. This mirrors what an agent receives over stdio; everything is local, so no other servers are needed:

import asyncio

from iso20022_bank_profile_mcp import server


async def main() -> None:
    async def call(name, args):
        result = await server.server.call_tool(name, args)
        # mcp 2.x returns a CallToolResult (use .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 ""

    # Which clearing profiles can I target?
    print(await call("list_profiles", {}))
    # -> {"profile_id": "...", "market_practice": "...", "rule_count": ...}, ...

    # Lint a payload against a profile: a CBPR+ address missing its town.
    payload = "<Document><PstlAdr><Ctry>DE</Ctry></PstlAdr></Document>"
    print(await call("lint_payload",
                     {"payload_content": payload, "profile_id": "CBPR+"}))
    # -> {"profile_id": "CBPR+", "is_compliant": false,
    #     "findings": [{"code": "CBPR_MISSING_TOWN", "locator": "TwnNm", ...}]}


asyncio.run(main())

Tools

All tools return JSON-serialisable data; on a domain, validation, or value error they return an {"error": ...} payload rather than raising. Every tool is a pure, local, read-only, idempotent, closed-world lookup — no network, no sub-servers.