io.github.sebastienrousseau/acmt001-mcp

acmt001-mcp: An MCP Server for ISO 20022 Account Management

![acmt001-mcp banner][banner]

A [Model Context Protocol][mcp] server that exposes the [acmt001][core] ISO 20022 Account Management library as tools for AI agents and assistants — discover message types, inspect input schemas, validate records and financial identifiers, and generate validated XML, all from your favourite MCP client.

Latest release: v0.0.13: 7 MCP tools over stdio, streamable HTTP or SSE, all backed by the shared acmt001.services layer, for Python 3.10+. Ships in lockstep with acmt001 0.0.13; every CI and image install is hash-pinned, and the tools are fuzzed. [See what's new →][release-0013]

Contents

• Overview
• Install
• Quick Start
• Transports
• Tools
• Using the tools
• Benchmarks
• Documentation
• Development
• License
• Contribution
• 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. acmt001-mcp is an MCP server that turns the [acmt001][core] library into a set of first-class agent tools, so an assistant can generate and validate ISO 20022 acmt Account Management XML messages — the standardised instructions, confirmations, and reports that govern the lifecycle of a bank account (opening, maintenance, closing, identification, and switching) — directly from a conversation.

Every tool is a thin, typed wrapper over acmt001.services — the single shared facade also 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.

• Website: https://acmt001.com
• Source code: https://github.com/sebastienrousseau/acmt001-mcp
• Bug reports: https://github.com/sebastienrousseau/acmt001-mcp/issues

This package is part of the acmt001 suite — a set of independently installable packages that share the acmt001.services layer:

• [acmt001][core] — the core library (CLI + REST API)
• acmt001-mcp — this package, the Model Context Protocol server
• [acmt001-lsp][lsp] — the Language Server Protocol server for editors

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

Install

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

python -m pip install acmt001-mcp

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

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

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 acmt001-mcp

Quick Start

Launch the server over stdio (the default transport):

acmt001-mcp

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

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

The agent can then call the tools below to validate account data and generate ISO 20022 messages on demand.

Transports

One command line, three transports:

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

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

Tools

All tools delegate to the shared acmt001.services layer, so they behave identically to the CLI and REST API.

• list_message_types — List the 34 supported acmt message types
• 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
• validate_identifier — Validate an IBAN, BIC, or LEI
• generate_message — Generate a validated acmt XML message
• verify_lei_online — Look an LEI up in the live GLEIF register (needs the online extra)

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 acmt001_mcp.server import server

# A single flat account-opening record.
record = [
    {
        "msg_id": "ACMT-MSG-0001",
        "creation_date_time": "2026-01-15T10:30:00",
        "process_id": "ACMT-PRC-0001",
        "account_id": "GB29NWBK60161331926819",
        "account_currency": "EUR",
        "account_name": "Treasury Operating Account",
        "account_type_cd": "CACC",
        "account_servicer_bic": "NWBKGB2LXXX",
        "account_owner_name": "Acme Embedded Finance Ltd",
        "account_owner_country": "GB",
        "org_full_legal_name": "Acme Embedded Finance Limited",
        "org_country_of_operation": "GB",
        "org_id_lei": "5493001KJTIIGC8Y1R12",
    }
]


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

    # Validate an identifier.
    print(await call("validate_identifier",
                     {"kind": "lei", "value": "5493001KJTIIGC8Y1R12"}))
    # -> {"kind": "lei", "value": "5493001KJTIIGC8Y1R12", "valid": true}

    # Generate a validated ISO 20022 Account Opening Request.
    xml = await call("generate_message",
                     {"message_type": "acmt.007.001.05", "records": record})
    print(xml[:46])  # -> <?xml version="1.0" encoding="UTF-8"?> ...


asyncio.run(main())

Run it directly:

python examples/mcp_tools.py

Benchmarks

python benches/bench_tool_dispatch.py           # full run
python benches/bench_tool_dispatch.py --quick   # what CI runs

The benchmark measures what an agent waits for: the dispatch floor (list_message_types, around a microsecond), the metadata lookups used to build a request, and the two batch tools side by side.

The result worth knowing is the asymmetry between those two. validate_records checks every record, so it is linear in batch size. generate_message, for a single-account message type like the default acmt.007.001.05, renders only the first record — twenty-seven of the thirty-four templates work this way. So validating a hundred records and generating from them costs roughly 260 ms of validation against 6 ms of generation, and returns one message rather than a hundred.

That is correct ISO 20022 behaviour and a real trap when batching, which is why the benchmark prints output size beside the timings: flat bytes across growing input is what tells you the rest of the batch was not rendered. See docs/benchmarks.md.

Documentation

• Rendered docs (API reference, ADRs, benchmarks, changelog): sebastienrousseau.github.io/acmt001-mcp
• Runnable example: examples/mcp_tools.py
• Architecture decisions: docs/adr/
• Release history: CHANGELOG.md
• Core library docs: acmt001.com
• MCP specification: modelcontextprotocol.io

Development

acmt001-mcp uses Poetry and mise.

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

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

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

make check        # all gates (REQUIRED before commit)
make test         # pytest, 100% line and 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 on the score
make docs         # Sphinx site, warnings are errors

The property-based tests (Hypothesis) run as part of make test; set HYPOTHESIS_PROFILE=mutation for the slimmer profile the mutation run uses.

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/acmt001-mcp

License

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

Contribution

Contributions are welcome — see the [contributing instructions][04]. Thanks to all [contributors][05].

Acknowledgements

Built on the [acmt001][core] ISO 20022 Account Management library and the [Model Context Protocol][mcp] Python SDK.

[01]: https://opensource.org/license/apache-2-0/ [04]: https://github.com/sebastienrousseau/acmt001-mcp/blob/main/CONTRIBUTING.md [05]: https://github.com/sebastienrousseau/acmt001-mcp/graphs/contributors [core]: https://github.com/sebastienrousseau/acmt001 [lsp]: https://github.com/sebastienrousseau/acmt001-lsp [mcp]: https://modelcontextprotocol.io [release-0013]: https://github.com/sebastienrousseau/acmt001-mcp/releases/tag/v0.0.13 [release-005]: https://github.com/sebastienrousseau/acmt001-mcp/releases/tag/v0.0.5 [release-002]: https://github.com/sebastienrousseau/acmt001-mcp/releases/tag/v0.0.2 [release-001]: https://github.com/sebastienrousseau/acmt001-mcp/releases/tag/v0.0.1 [banner]: https://kura.pro/acmt001-mcp/images/banners/banner-acmt001-mcp.svg 'acmt001-mcp'