Reconcile Mcp

reconcile-mcp: An MCP Server for ISO 20022 Cash Reconciliation

[Build Status] [PyPI version] [Glama MCP server score] [OpenSSF Scorecard] [License] [Python Version]

[reconcile-mcp Demo]

A Model Context Protocol server that matches expected payments (from pain.001 credit transfers) against observed booked entries (from a camt.053 statement) and returns an explainable reconciliation — exact matches, short/over payments, split settlements (one-to-many), batch credits (many-to-one), and the residual unmatched items on each side, every match carrying a score and the reasons it was made.

Latest release: v0.0.7: 10 MCP tools over stdio, streamable HTTP or SSE, pure-Python matching engine, deterministic sandbox test-mode, for Python 3.10+. Part of the ISO 20022 MCP suite: you own both sides of the match.

Why this exists

Reconciliation is the treasury team's daily pain: did the money we expected actually arrive, and which invoice does each credit belong to? It is rarely one-to-one — customers underpay, settle an invoice in instalments, or a payout aggregator sends one lump covering a dozen receivables. reconcile-mcp does this matching as an agent tool, and — critically for finance — shows its work: every pairing comes with a numeric score and a plain list of the signals (reference, amount, date, counterparty) that drove it.

The ISO 20022 MCP Suite

reconcile-mcp is the reconciliation workflow of eight coordinated, vendor-neutral MCP servers that together cover the ISO 20022 bank-statement workflow and the November 2026 structured-address cutover, plus a high-level orchestration layer — readiness scoring, clearing-profile linting, and audit evidence — statement depth, whole-catalogue routing, reconciliation, multi-format ingestion, and address remediation. 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.

In one line each: camt053-mcp is the bank-statement flagship (deepest camt.05x surface, stdio + authenticated streamable HTTP); iso20022-mcp is the generic message toolkit (a handful of verbs over the whole catalogue); reconcile-mcp is the reconciliation workflow (did the money we expected actually arrive?); bankstatementparser-mcp is the ingestion layer (many formats in, one transaction shape out); and structured-address-fix-mcp is the postal-address specialist (debtor/creditor addresses cliff-ready for the Nov 2026 cutover).

The suite also includes per-family servers — pain001-mcp (credit transfer initiation), pacs008-mcp (FI-to-FI credit transfers), and acmt001-mcp (account management) — whose parsed output feeds straight into this server's normalize_* adapters.

Install

pip install reconcile-mcp# or run without installing:uvx reconcile-mcp

MCP client config (e.g. Claude Desktop claude_desktop_config.json):

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

Quick start (zero real data)

The server ships a sandbox test-mode: deterministic scenarios so you can run the whole flow with no setup and no real cash data. One call gets you a full, explainable result:

run_sandbox_scenario(name="month_end")

returns a realistic mixed close — one clean match, one short payment, one split settlement, and an unexpected credit correctly left unmatched:

{  "summary": {    "expected_count": 3, "observed_count": 5,    "matched_expected": 3, "unmatched_observed": 1,    "matches_by_type": {"exact": 1, "amount_mismatch": 1, "one_to_many": 1},    "fully_reconciled": false  },  "matches": [    {"type": "amount_mismatch", "expected": ["INV-6002"], "observed": ["ENT-52"],     "amount_delta": "-99.99", "confidence": "high",     "reasons": ["reference exact", "amount close (delta -99.99)", "date +/-0d", "counterparty exact"]},    {"type": "exact", "expected": ["INV-6001"], "observed": ["ENT-51"], "amount_delta": "0.00"},    {"type": "one_to_many", "expected": ["INV-6003"], "observed": ["ENT-53", "ENT-54"],     "reasons": ["amount sum of 2 entries"]}  ],  "unmatched_observed": ["ENT-55"]}

List every scenario with list_sandbox_scenarios; load one to inspect or edit its inputs with load_sandbox_scenario.

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

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

Bring your own data

Records are small canonical objects — id and amount required, everything else optional and used to sharpen matching:

{  "id": "INV-1001",            // your reference / end-to-end id  "amount": 1200.00,  "currency": "EUR",           // ISO 4217  "date": "2026-03-02",        // ISO-8601  "counterparty": "Acme Ltd",  "reference": "INV-1001"      // remittance / structured reference}

Already using the rest of the suite? Feed parsed output straight in — the adapters map it for you:

• normalize_pain001(document) → the expected side, from pain001-mcp.
• normalize_camt053(document) → the observed side, from camt053-mcp.

Then call reconcile(expected, observed).

Tools

• reconcile — Match expected payments against observed entries; full explainable report.
• explain_match — Score a single expected/observed pair with a per-signal breakdown (tuning aid).
• normalize_pain001 — Adapt parsed pain.001 output into canonical expected records.
• normalize_camt053 — Adapt parsed camt.053 output into canonical observed records.
• list_sandbox_scenarios — List the built-in test-mode scenarios and magic references.
• load_sandbox_scenario — Return one scenario's expected/observed inputs to inspect or edit.
• run_sandbox_scenario — Load a scenario and reconcile it in one call — the fastest first run.
• match_names_probabilistic — Score two counterparty names by Jaro-Winkler similarity and flag a match at a threshold.
• match_amounts_with_fx_drift — Compare two amounts in different currencies through a supplied FX rate, within a percentage tolerance.
• reconcile_many_to_many — Match each deposit to a disjoint subset of invoices whose amounts sum to it (subset-sum ILP; needs the ilp extra).

Plus one prompt and two resources:

• Prompt reconcile_workflow — Step-by-step guidance from raw pain.001/camt.053 to an explained match report.
• Resource reconcile://sandbox-scenarios — The built-in scenario catalogue.
• Resource reconcile://sandbox/{scenario_id} — One scenario's expected/observed inputs.

How matching works

Each candidate pair is scored on four weighted signals, then classified:

• Reference (0.45) — exact / partial equality of references and end-to-end ids, normalised to bare alphanumerics.
• Amount (0.35) — exact within tolerance, or a linearly-decaying closeness with the delta reported.
• Date (0.10) — proximity within a configurable window; neutral if unknown.
• Counterparty (0.10) — token-set overlap of names; neutral if unknown.

Assignment is greedy, highest-score-first and fully deterministic (a total tiebreak order), so the same inputs always produce the same result. Residuals are then tested for one-to-many (a bounded subset-sum: one expected settled by several entries) and many-to-one (one entry covering several expected).

Tune any of it via the options argument: abs_tol / rel_tol, date_window_days, high_threshold, review_threshold, currency_strict, enable_one_to_many, max_combination.

Development

git clone https://github.com/sebastienrousseau/reconcile-mcpcd reconcile-mcppython -m venv .venv && . .venv/bin/activatepip install -e . && pip install pytest pytest-cov ruff black mypypytest                      # 100% branch coverage gateruff check reconcile_mcp tests && black --check reconcile_mcp tests && mypy reconcile_mcp

License

Licensed under the Apache License, Version 2.0 or the MIT License, at your option.

mcp-name: io.github.sebastienrousseau/reconcile-mcp