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

PyPI Version Python Versions License Tests Quality OpenSSF Scorecard Documentation

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

The 14 November 2026 cliff. On that date CBPR+, HVPS+, T2, CHAPS, and Fedwire stop accepting fully unstructured postal addresses: a payment whose debtor/creditor address is a free-text blob is rejected. structured-address-fix-mcp puts the readiness check and the fix in front of your agent — assess_message flags the offending parties, remediate_message proposes the compliant form, and get_cutover_date reports the binding date. v0.0.2, stdio transport, 13 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 agents and assistants discover and call external tools in a uniform way. structured-address-fix-mcp is an MCP server that turns the structured-address-fix library into a set of first-class agent tools, so an assistant can read a postal address — or every addressed party in an ISO 20022 pacs.008 / pain.001 message — and bring it into line with the structured-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 the compliant 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 behave identically. 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 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: start with one, add the rest as your workflow grows.

The suite also includes the iso20022-mcp gateway (unified search / describe / validate / generate / parse meta-tools across the whole message catalogue) and acmt001-mcp (account management). Where pacs008-mcp lints a message for address problems, structured-address-fix-mcp is the specialist that classifies, assesses, and fixes the addresses themselves against per-scheme policies.

Install

structured-address-fix-mcp runs on macOS, Linux, and Windows and requires Python 3.12+ and pip. It pulls in the core structured-address-fix library 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 conversation tutorial, 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 the client'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 an MCP client, not used interactively. The agent can then call the tools below to assess and remediate postal addresses on demand.

Tools

All tools delegate to the shared structured_address_fix.services layer, so they behave identically to the CLI. Tools return JSON-serialisable data; on a domain, 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
• normalize_country_code — Resolve a country name or code to its ISO 3166-1 alpha-2 code, accepting English names, local endonyms (Deutschland, España, Nippon) and everyday aliases (UK, USA, Holland, UAE)
• split_street_and_building — Split a street line into street name, building and sub-building, handling both the leading-number convention (10 Downing Street) and the trailing-number one used across much of continental Europe
• validate_postal_policy — Validate an address's post_code against a country's format policy (US ZIP / ZIP+4, GB alphanumeric, and others)
• parse_address_libpostal — Parse a free-text address into ISO 20022 postal fields; uses libpostal's statistical parser when the optional postal extra is installed, and a deterministic fallback otherwise

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

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. The runnable version 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)
        # mcp 2.x returns a CallToolResult (read .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 ""

    # 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 MCP servers 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 an MCP-aware host (Claude Desktop, the IDE plugins, an agent framework). For scripted / CI use, the structured-address-fix CLI covers the same ground without 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. An HTTP/OAuth transport for shared, multi-tenant deployments is on the roadmap, not in this release.
• You need streaming responses. Tool calls return whole values, not streams. Large messages are assessed and remediated in one call, not chunked over multiple responses.
• You need to build the pacs.008 / pain.001 message. Out of scope; this server fixes the addresses inside a message. Use pacs008-mcp or pain001-mcp to generate and validate the message itself.

Development

structured-address-fix-mcp uses Poetry and mise.

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 the sibling checkout (../structured-address-fix); see CONTRIBUTING.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 to structured_address_fix.services, where the defence-in-depth for XML parsing (defusedxml) lives. Tools catch the documented domain, validation, and value errors and return an {"error": ...} envelope per the suite convention; they never propagate raw exceptions to the MCP client. Reporting practice, supported versions, and the full supply-chain posture (SLSA L3 provenance, PEP 740 attestations, SBOMs, and the NIST SP 800-218 SSDF practice mapping) are documented in SECURITY.md. Vulnerabilities go via GitHub Private 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 submitted for inclusion shall be licensed as above, without additional terms.

Contributing

Contributions are welcome — see the contributing instructions. Thanks to all contributors.

Acknowledgements

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