Skip to main content
Glama

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

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

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.8: 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.

Related MCP server: fincon

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.

Server

Scope

Surface

Install

Use it when

camt053-mcp

ISO 20022 camt.053/camt.052 bank statements: parse, validate, filter, reverse; MT940/MT942 migration; CBPR+ readiness; journal export

24 MCP tools · 4 prompts · 3 resources

pip install camt053-mcp

You work with bank-to-customer statements end to end — the suite's flagship

iso20022-mcp

Unified gateway: search / describe / validate / generate / parse meta-tools routed across the pain · pacs · camt · acmt families

7 meta-tools

pip install "iso20022-mcp[all]"

You want one entry point to every message family

reconcile-mcp

Matches expected pain.001 payments against observed camt.053 entries — exact, partial, one-to-many, many-to-one, every match scored and explained

10 MCP tools · 1 prompt · 2 resources

pip install reconcile-mcp

You need explainable statement/payment reconciliation — this package

bankstatementparser-mcp

Multi-format statement ingestion: ISO 20022 CAMT.053 and pain.001, SWIFT MT940, OFX/QFX, CSV

5 MCP tools · 1 prompt · 1 resource

pip install bankstatementparser-mcp

Your statements arrive in mixed or legacy formats

structured-address-fix-mcp

ISO 20022 postal-address classification, assessment & remediation for the November 2026 structured-address cutover (pacs.008 / pain.001 debtor & creditor addresses)

9 MCP tools

pip install structured-address-fix-mcp

You need debtor/creditor addresses cliff-ready ahead of 14 Nov 2026

iso20022-readiness-suite-mcp

Orchestration gateway: detect → structurally validate → clearing-profile lint → readiness score, plus automated remediation and pacs.002 bank-response simulation — a meta-client over the foundational servers

4 MCP tools

pip install iso20022-readiness-suite-mcp

You want one high-level readiness / orchestration entry point over the suite

iso20022-bank-profile-mcp

Manages, validates and serves bank-specific clearing profiles / rule packs (CBPR+, SEPA_Instant, FedNow, Generic); premium rule-pack entitlement gating

4 MCP tools

pip install iso20022-bank-profile-mcp

You lint payments against your own institution's market practice

iso20022-evidence-pack-mcp

Compiles readiness findings, remediation diffs and simulated responses into a sealed, Ed25519-signable audit evidence pack

6 MCP tools

pip install iso20022-evidence-pack-mcp

You need tamper-evident audit / certification artifacts

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:

Command

Transport

Endpoint

Protocol revisions

reconcile-mcp

stdio

the client spawns the process

2026-07-28, 2025-11-25

reconcile-mcp --transport streamable-http

Streamable HTTP

http://127.0.0.1:8000/mcp

2026-07-28 (stateless, server/discover) and 2025-11-25 (initialize, Mcp-Session-Id) on the same endpoint; responses stream as server-sent events, GET opens the server-to-client stream

reconcile-mcp --transport sse

HTTP+SSE (2024-11-05)

http://127.0.0.1:8000/sse and /messages/

for clients that still expect the older transport

--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-mcp
cd reconcile-mcp
python -m venv .venv && . .venv/bin/activate
pip install -e . && pip install pytest pytest-cov ruff black mypy
pytest                      # 100% branch coverage gate
ruff 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

Available Tools

10 tools
explain_matchA
Read-onlyIdempotent

Explain the match score between one expected and one observed record.

Purpose: Scores a single transaction pair across reference, amount, date, and name signals, returning individual signal weights and an explanation even for pairs below threshold.

When to use:

  • When tuning scoring weights, tolerances, or debugging match decisions.

  • When explaining match confidence for human review or exception handling.

When NOT to use:

  • Scores one pair rather than an entire batch; use reconcile for multi-record batches.

  • Compares amounts directly rather than converting across currencies; use match_amounts_with_fx_drift with an explicit FX rate.

Behavioral transparency: Pure, deterministic, side-effect-free, read-only calculation without external dependencies.

Inputs: expected (required), observed (required), options. Returns: object

list_sandbox_scenariosA
Read-onlyIdempotent

List built-in sandbox reconciliation scenarios and magic references.

Purpose: Returns the catalog of deterministic test-mode scenarios and synthetic magic references to demonstrate reconciliation outcomes without production data.

When to use:

  • When discovering available test scenarios (e.g. clean_match, month_end, fx_drift).

  • When testing agent decision-making workflows with zero setup.

When NOT to use:

  • Returns static synthetic test fixtures only, not production reconciliation batches.

Behavioral transparency: Static catalogue retrieval; read-only and instantaneous.

Inputs: no named parameters. Returns: object

load_sandbox_scenarioA
Read-onlyIdempotent

Load expected and observed record inputs for a named sandbox scenario.

Purpose: Retrieves the test-mode expected and observed fixture records for a named scenario so they can be inspected, customized, or passed to reconcile.

When to use:

  • When reviewing fixture data prior to executing reconciliation runs.

  • When creating custom variations of standard reconciliation scenarios.

When NOT to use:

  • Returns raw fixture inputs without running matching; use run_sandbox_scenario to load and reconcile a scenario in one step.

  • Requires a registered scenario name from list_sandbox_scenarios.

Behavioral transparency: Deterministic dictionary lookup; read-only with no side effects.

Inputs: name (required). Returns: object

match_amounts_with_fx_driftMatch amounts (FX drift)A
Read-onlyIdempotent

Compare two amounts in different currencies within an FX drift tolerance.

Purpose: Converts currency amounts using a provided exchange rate and verifies if the percentage difference falls within an acceptable tolerance window using exact decimal arithmetic.

When to use:

  • When reconciling cross-currency payments with conversion timing or rate variance.

  • When evaluating FX tolerance bounds on cross-border transactions.

When NOT to use:

  • Designed for cross-currency comparisons with a positive fx_rate; use reconcile for same-currency tolerance matching.

  • Rejects zero or negative FX rates.

Behavioral transparency: Pure mathematical calculation; read-only and idempotent.

Inputs: fx_rate (required), amount_a (required), amount_b (required), currency_a (required), +2 more. Returns: object

match_names_probabilisticMatch names (probabilistic)A
Read-onlyIdempotent

Score two counterparty names using Jaro-Winkler string similarity.

Purpose: Computes similarity in [0, 1] between two company or individual names, tolerating typographical variations and legal suffix abbreviations (e.g. 'Corp' vs 'Corporation Inc').

When to use:

  • When verifying whether two counterparty or entity names represent the same party.

  • When evaluating name similarity thresholds for automated matching rules.

When NOT to use:

  • Scores counterparty name strings in isolation rather than full multi-signal transaction records; use reconcile or explain_match for full records.

  • Accepts string inputs only.

Behavioral transparency: Pure, deterministic string calculation; read-only and idempotent.

Inputs: name_a (required), name_b (required), threshold. Returns: object

normalize_camt053A
Read-onlyIdempotent

Convert parsed camt.053 statement entries into canonical observed records.

Purpose: Adapts parsed ISO 20022 camt.053 bank statement documents or entry lists into canonical observed records ready for the reconcile engine.

When to use:

  • When converting parsed bank statements into canonical observed records for reconcile.

  • When transforming bank booking entries into uniform id, amount, date, and counterparty fields.

When NOT to use:

  • Accepts parsed camt.053 bank statements only, not payment initiation orders (pain.001); use normalize_pain001 for payments.

  • Expects a parsed dictionary or list rather than raw XML text.

Behavioral transparency: Pure, deterministic, read-only data normalization.

Inputs: document (required). Returns: object

normalize_pain001A
Read-onlyIdempotent

Convert parsed pain.001 payment instructions into canonical expected records.

Purpose: Adapts parsed ISO 20022 pain.001 credit transfer documents or transaction lists into canonical expected records ready for the reconcile engine.

When to use:

  • When converting parsed pain.001 files into canonical expected records for reconcile.

  • When mapping diverse payment field structures into uniform id, amount, and reference fields.

When NOT to use:

  • Accepts parsed pain.001 payment orders only, not bank statement entries (camt.053); use normalize_camt053 for statements.

  • Expects a parsed dictionary or list rather than raw XML text.

Behavioral transparency: Pure, deterministic, read-only data normalization.

Inputs: document (required). Returns: object

reconcileA
Read-onlyIdempotent

Reconcile expected payments against observed bank-statement entries.

Purpose: Matches expected payment instructions (e.g. from pain.001) against observed bank transactions (e.g. from camt.053) and produces an explainable reconciliation report covering exact matches, short/over adjustments, split settlements (one-to-many), batch credits (many-to-one), and unmatched residuals.

When to use:

  • When performing multi-transaction cash reconciliation between ledgers and statements.

  • When transparent per-match confidence scores and reason breakdowns are required for audit.

When NOT to use:

  • Expects canonical record dicts rather than raw XML; normalize parsed inputs first with normalize_pain001 or normalize_camt053.

  • Evaluates full batches rather than single-pair tuning analysis; use explain_match to inspect one pair.

  • Runs greedy and bounded matching rather than unconstrained combinatorial invoice subsets; use reconcile_many_to_many for subset-sum ILP.

Behavioral transparency: Pure, deterministic, side-effect-free, read-only calculation without network or disk access.

Inputs: expected (required), observed (required), options. Returns: object

reconcile_many_to_manyReconcile many-to-manyA
Read-onlyIdempotent

Match statement deposits to disjoint subsets of invoices via subset-sum ILP.

Purpose: Solves bounded subset-sum as an integer linear program (ILP) to pair statement deposits against matching combinations of outstanding invoice records.

When to use:

  • When customer deposits consolidate multiple invoices or split remittances.

  • When one-to-one or one-to-many heuristics leave unmatched aggregates.

When NOT to use:

  • Solves combinatorial subset-sum rather than standard 1:1 or 1:N reconciliation, where reconcile is faster.

  • Requires the optional ilp extra (pip install reconcile-mcp[ilp]).

Behavioral transparency: Deterministic ILP optimization; read-only and idempotent.

Inputs: invoices (required), statements (required). Returns: object

run_sandbox_scenarioA
Read-onlyIdempotent

Load a named sandbox scenario and immediately return its reconciliation report.

Purpose: One-call execution that loads built-in fixture records and executes the reconciliation pipeline, returning a complete explainable match report.

When to use:

  • When performing quick verification, smoke tests, or initial agent demonstrations.

  • When verifying tolerance tuning against standard test cases.

When NOT to use:

  • Operates on built-in synthetic fixtures rather than live production data.

  • Uses fixed scenario inputs; use reconcile to supply custom expected and observed records.

Behavioral transparency: Deterministic, in-memory execution; read-only and idempotent.

Inputs: name (required), options. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool has a sharply bounded role, and descriptions explicitly cross-reference the alternative tool to use instead (e.g. reconcile vs reconcile_many_to_many vs explain_match, list/load/run_sandbox_scenario). Overlap-prone pairs are differentiated by input shape, scope, and output, so misselection is unlikely.

    Naming Consistency4/5

    Consistent snake_case with verb-first naming (normalize_pain001, match_names_probabilistic, run_sandbox_scenario, reconcile_many_to_many). Minor deviations: the bare `reconcile` verb and adjective suffixes like `_probabilistic`/`_with_fx_drift` break the strict verb_noun rhythm.

    Tool Count5/5

    Ten tools is well within the ideal range and every tool earns its place: normalization, core matching, pair-level explanation, specialist matchers, and sandbox fixtures. No redundant wrappers or filler tools.

    Completeness4/5

    Covers the full lifecycle: ingest normalization for both ISO 20022 directions, batch and pairwise matching, FX and name signals, ILP subset matching, and sandbox fixtures for testing. Minor gaps exist around report export/persistence and other message types (e.g. pain.002, camt.052), but core workflows have no dead ends.

    Maintenance

    ActivityActive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Unified gateway for ISO 20022 message families, providing meta-tools to search, describe, validate, generate, and parse financial messages.
      7
      89 PyPI
      1
      Apache 2.0
    • F
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to perform financial reconciliation with a deterministic proof engine: intake files, match transactions, verify proofs, resolve exceptions, and sign off on balanced journals under the user's authority.
      21
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI IDEs to perform financial reconciliation through five native tools for matching invoices, detecting bundled payments, and handling bank fee variances.
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables parsing of structured financial receipts, invoices, and bank statements, tolerance-based three-way reconciliation, detection of tax calculation drift and duplicate claims, and synthesis of double-entry bookkeeping journal entries.
      MIT