structured-address-fix-mcp: An MCP Server for ISO 20022 Postal Addresses

structured-address-fix-mcp: An MCP Server for ISO 20022 Postal Addresses

A Model Context Protocol server that exposes thestructured-address-fix ISO 20022 postal-address library as tools forAI agents and assistants — classify an address's shape, assess it against ascheme policy, and remediate it (or a whole pacs.008 / pain.001 message) intothe structured form the November 2026 cutover requires, all from yourfavourite MCP client.

The 14 November 2026 cliff. On that date CBPR+, HVPS+, T2, CHAPS, andFedwire stop accepting fully unstructured postal addresses: a payment whosedebtor/creditor address is a free-text blob is rejected. structured-address-fix-mcpputs the readiness check and the fix in front of your agent — assess_messageflags the offending parties, remediate_message proposes the compliant form,and get_cutover_date reports the binding date. v0.0.2, stdio transport,9 tools, Python 3.12+.

Contents

• Overview
• The ISO 20022 MCP Suite
• Install
• Quick Start
• Tools
• Using the tools
• Related MCP Servers
• When not to use structured-address-fix-mcp
• Development
• Security
• Documentation
• License
• Contributing
• Acknowledgements

Overview

The Model Context Protocol (MCP) is an open standard that lets AI agentsand assistants discover and call external tools in a uniform way.structured-address-fix-mcp is an MCP server that turns thestructured-address-fix library into a set of first-class agent tools,so an assistant can read a postal address — or every addressed party in anISO 20022 pacs.008 / pain.001 message — and bring it into line with thestructured-address rules that become mandatory on 14 November 2026,directly from a conversation.

The headline capability is the one-shot remediation workflow: assess a message,find the parties whose addresses will be rejected at the cliff, and emit thecompliant form with each change explained and confidence-scored.

Every tool is a thin, typed wrapper over structured_address_fix.services —the single shared facade also used by the CLI — so all interfaces behaveidentically. Tools return JSON-serialisable data; on an error they return an{"error": ...} payload rather than raising.

• Website: https://sebastienrousseau.github.io/structured-address-fix/
• Source code: https://github.com/sebastienrousseau/structured-address-fix-mcp
• Bug reports: https://github.com/sebastienrousseau/structured-address-fix-mcp/issues

flowchart LR
    A["MCP client<br/>(Claude Desktop, IDE, agent)"] -->|stdio| B["structured-address-fix-mcp"]
    B -->|delegates to| C["structured_address_fix.services"]
    C -->|classify + assess + remediate| D["ISO 20022 postal addresses<br/>(pacs.008 / pain.001)"]

The ISO 20022 MCP Suite

structured-address-fix-mcp is the postal-address specialist in a set ofcoordinated, vendor-neutral MCP servers for the ISO 20022 migration.Dependency ranges are kept aligned across the suite, so the servers co-installcleanly in a single Python environment: start with one, add the rest as yourworkflow grows.

The suite also includes the iso20022-mcpgateway (unified search / describe / validate / generate / parsemeta-tools across the whole message catalogue) andacmt001-mcp (accountmanagement). Where pacs008-mcp lints a message for address problems,structured-address-fix-mcp is the specialist that classifies, assesses, andfixes the addresses themselves against per-scheme policies.

Install

structured-address-fix-mcp runs on macOS, Linux, and Windows and requiresPython 3.12+ and pip. It pulls in the core structured-address-fixlibrary and the MCP SDK automatically.

python -m pip install structured-address-fix-mcp

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

Quick Start

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

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

structured-address-fix-mcp

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

{
  "mcpServers": {
    "structured-address-fix": { "command": "structured-address-fix-mcp" }
  }
}

The command speaks MCP on stdin/stdout — it is meant to be launched by anMCP client, not used interactively. The agent can then call the tools belowto assess and remediate postal addresses on demand.

Tools

All tools delegate to the shared structured_address_fix.services layer, sothey behave identically to the CLI. Tools return JSON-serialisable data; on adomain, validation, or value error they return an {"error": ...} payload.

• list_policies — List every available address policy (rulebook) with its tier (e.g. cbpr-2026, sepa, hvps-plus, generic-structured)
• classify_address — Classify a postal address as structured, hybrid, or unstructured (a quick shape check)
• assess_address — Score a single address against a policy and return its findings
• assess_message — Assess every addressed party in a pacs.008 / pain.001 message against a policy
• remediate_address — Propose the compliant form of an address, with the before/after and confidence-scored patch operations
• remediate_message — Assess and remediate every addressed party in a message; optionally apply the operations and return the patched XML
• preview_patch — Return the patch operations remediation would apply to a message (a dry run)
• explain_finding — Explain what a finding code (e.g. SAF001) means and how to resolve it
• get_cutover_date — Return the binding November 2026 structured-address cutover date and the scheme that sets it

Optional parameters shared across the assessment/remediation tools: policy_id(defaults to cbpr-2026), as_of (an YYYY-MM-DD date that decides the cliffwording; defaults to today), and country_hint (an ISO 3166-1 alpha-2 code toassume when an address carries no country of its own).

Using the tools

You can invoke the tools in-process — without a transport — straight through theFastMCP instance. This mirrors what an agent receives over stdio. The runnableversion of this snippet lives in examples/mcp_tools.py.

import asyncio

from structured_address_fix_mcp import server

# A fully unstructured address: two free-text lines, no structured fields.
# At the 14 Nov 2026 cliff this form is rejected across the major schemes.
unstructured = {
    "address_lines": ["10 Downing St", "London SW1A 2AA"],
    "country": "GB",
}


async def main() -> None:
    async def call(name, args):
        result = await server.server.call_tool(name, args)
        content = result[0] if isinstance(result, tuple) else result
        return content[0].text if content else ""

    # When does the cliff bite?
    print(await call("get_cutover_date", {}))
    # -> {"date": "2026-11-14", "scheme": "SWIFT CBPR+ UG2026"}

    # What shape is this address in right now?
    print(await call("classify_address", {"address": unstructured}))
    # -> {"classification": "unstructured"}

    # Propose the compliant form, with each change explained.
    print(await call("remediate_address",
                     {"address": unstructured, "policy_id": "cbpr-2026"}))
    # -> {"policy_id": "cbpr-2026", "findings": [...], "suggestions": [...],
    #     "is_compliant_before": false, "is_compliant_after": true, ...}


asyncio.run(main())

Run it directly:

python examples/mcp_tools.py

Related MCP Servers

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

When not to use structured-address-fix-mcp

• You have no MCP client. This server only makes sense paired with anMCP-aware host (Claude Desktop, the IDE plugins, an agent framework). Forscripted / CI use, the structured-address-fix CLI covers the same groundwithout the stdio protocol overhead.
• You need a long-lived network service. v0.1 speaks stdio only —one process per operator, launched by the client, no network surface. AnHTTP/OAuth transport for shared, multi-tenant deployments is on theroadmap, not in this release.
• You need streaming responses. Tool calls return whole values, notstreams. Large messages are assessed and remediated in one call, notchunked over multiple responses.
• You need to build the pacs.008 / pain.001 message. Out of scope; thisserver fixes the addresses inside a message. Usepacs008-mcp orpain001-mcp togenerate and validate the message itself.

Development

structured-address-fix-mcp uses Poetry andmise.

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

Note: the server depends on the core structured-address-fix library.Until it is published to PyPI, the dev dependency group installs it from thesibling checkout (../structured-address-fix); seeCONTRIBUTING.md.

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

make check        # all gates (REQUIRED before commit): lint + type-check + test + examples
make test         # pytest
make lint         # ruff + black
make type-check   # mypy --strict
make security     # bandit

Security

structured-address-fix-mcp is a thin wrapper — every tool delegates tostructured_address_fix.services, where the defence-in-depth for XML parsing(defusedxml) lives. Tools catch the documented domain, validation, and valueerrors and return an {"error": ...} envelope per the suite convention; theynever propagate raw exceptions to the MCP client. Reporting practice, supportedversions, and the full supply-chain posture (SLSA L3 provenance, PEP 740attestations, SBOMs, and the NIST SP 800-218 SSDF practice mapping) aredocumented in SECURITY.md. Vulnerabilities go via GitHubPrivate Vulnerability Reporting, not public issues.

Documentation

• README.md — this file
• CHANGELOG.md — release notes
• SECURITY.md — disclosure + supported versions
• SUPPORT.md — how to get help
• ROADMAP.md — what's next (HTTP/OAuth transport, observability, entitlement gating)
• MAINTAINERS.md — who can merge
• docs/quickstart.md — 10-minute install → first conversation
• docs/deployment-cookbook.md — stdio client configs (Claude Desktop, Cursor, containers)
• examples/ — runnable scripts
• glama.json — Glama directory manifest

MCP Registry

mcp-name: io.github.sebastienrousseau/structured-address-fix-mcp

License

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

Contributing

Contributions are welcome — see the contributing instructions. Thanks toall contributors.

Acknowledgements

Built on the structured-address-fix ISO 20022 postal-address libraryand the Model Context Protocol Python SDK.