reconcile-mcp
Summary: reconcile-mcp is a read-only MCP server for explainable ISO 20022 cash reconciliation between expected payments and observed bank-statement entries.
Reconcile full batches of canonical expected records against observed records, returning exact, amount-mismatch, one-to-many, many-to-one, and unmatched results with confidence scores and reasons.
Explain the score of a single expected/observed pair across reference, amount, date, and counterparty signals.
Normalize parsed pain.001 documents into expected records and parsed camt.053 documents into observed records.
List, load, and run deterministic sandbox scenarios for demos, smoke tests, and tolerance tuning.
Score counterparty name similarity with Jaro-Winkler and a configurable threshold.
Compare cross-currency amounts with a supplied FX rate and tolerance.
Run many-to-many reconciliation matching deposits to disjoint invoice subsets via subset-sum ILP when the optional ilp extra is installed.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@reconcile-mcp Reconcile my expected payments against observed bank entries."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
reconcile-mcp: An MCP Server for ISO 20022 Cash Reconciliation
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 |
ISO 20022 | 24 MCP tools · 4 prompts · 3 resources |
| You work with bank-to-customer statements end to end — the suite's flagship | |
Unified gateway: | 7 meta-tools |
| You want one entry point to every message family | |
Matches expected | 10 MCP tools · 1 prompt · 2 resources |
| You need explainable statement/payment reconciliation — this package | |
Multi-format statement ingestion: ISO 20022 CAMT.053 and pain.001, SWIFT MT940, OFX/QFX, CSV | 5 MCP tools · 1 prompt · 1 resource |
| Your statements arrive in mixed or legacy formats | |
ISO 20022 postal-address classification, assessment & remediation for the November 2026 structured-address cutover ( | 9 MCP tools |
| You need debtor/creditor addresses cliff-ready ahead of 14 Nov 2026 | |
Orchestration gateway: detect → structurally validate → clearing-profile lint → readiness score, plus automated remediation and | 4 MCP tools |
| You want one high-level readiness / orchestration entry point over the suite | |
Manages, validates and serves bank-specific clearing profiles / rule packs (CBPR+, SEPA_Instant, FedNow, Generic); premium rule-pack entitlement gating | 4 MCP tools |
| You lint payments against your own institution's market practice | |
Compiles readiness findings, remediation diffs and simulated responses into a sealed, Ed25519-signable audit evidence pack | 6 MCP tools |
| 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-mcpMCP 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 |
| stdio | the client spawns the process | 2026-07-28, 2025-11-25 |
| Streamable HTTP |
| 2026-07-28 (stateless, |
| HTTP+SSE (2024-11-05) |
| 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, frompain001-mcp.normalize_camt053(document)→ the observed side, fromcamt053-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 parsedpain.001output into canonical expected records.normalize_camt053— Adapt parsedcamt.053output 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 theilpextra).
Plus one prompt and two resources:
Prompt
reconcile_workflow— Step-by-step guidance from rawpain.001/camt.053to 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_mcpLicense
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 toolsexplain_matchARead-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_scenariosARead-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_scenarioARead-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)ARead-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)ARead-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_camt053ARead-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_pain001ARead-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
reconcileARead-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-manyARead-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_scenarioARead-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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Match bank receipts and payments to invoices with confidence, deductions and exceptions.
Check ISO 20022 messages (pacs.008, pain.001, camt.053, seev.031) against schema and rules.
Decode ISO 20022 pain.002 bank status reports & AC04/AM04/BE04/MD01/RC01 errors into plain English
Reconcile business documents, inspect exact differences and evidence, and export reports.
Related MCP Servers
- AlicenseAqualityBmaintenanceUnified gateway for ISO 20022 message families, providing meta-tools to search, describe, validate, generate, and parse financial messages.789 PyPI1Apache 2.0
- FlicenseBqualityCmaintenanceEnables 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-
- AlicenseNot gradedqualityCmaintenanceEnables AI IDEs to perform financial reconciliation through five native tools for matching invoices, detecting bundled payments, and handling bank fee variances.MIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables 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