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

[![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 [Model Context Protocol][mcp] server that exposes the [structured-address-fix][core] 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] (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][core] 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