Structured Address Fix MCP

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

[][07] [][07] [][01] [][tests-url] [][quality-url] [][scorecard-url] [][docs-url] [][glama-url]

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.6, stdio, streamable

HTTP and SSE transports, 13 tools, Python 3.12+.

Contents

• Overview
• The ISO 20022 MCP Suite
• Install
• Quick Start
• Transports — stdio, streamable HTTP (2026-07-28 and 2025-11-25) and SSE from one command line
• 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 (Claude Desktop, IDE, agent)"] -->|stdio, streamable HTTP or SSE| B["structured-address-fix-mcp"] B -->|delegates to| C["structured_address_fix.services"] C -->|classify + assess + remediate| D["ISO 20022 postal addresses (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

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 structured-address-fix-mcp

</details>

Quick Start

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

Launch the server over stdio (the 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 by default — it is meant to be launched by an MCP client, not used interactively. For a shared deployment or an HTTP client, see Transports. The agent can then call the tools below to assess and remediate postal addresses 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": { "structured-address-fix": { "url": "http://127.0.0.1:8000/mcp" } } }

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

#