payment-reconciliation-mcp

An MCP server that reconciles a vendor payment tracker against a bank export and tells you exactly where the two disagree.

The problem

In most small finance operations, the payment tracker and the bank are two separate sources of truth that quietly drift apart. Invoices get marked paid that never cleared. Payments bounce back and nobody notices until the vendor emails. The same vendor appears as "Acme Office Supplies Inc" in the tracker and "ACH DEBIT ACME OFFICE SUPPLIES INV 10432" on the bank statement, so a spreadsheet lookup finds nothing.

The usual fix is a person reading two files side by side once a month. That person misses things, and the misses cost money — I have run this reconciliation manually across dozens of vendor accounts and found outstanding payments nobody had flagged.

This server hands that job to Claude. You point it at both files and ask what doesn't match.

Related MCP server: taxformatter-mcp-server

What it does

Exposes three tools over MCP:

reconcile sorts every tracker row into exactly one of four primary buckets:

• Matched — tracker row and bank row agree on vendor and amount

• Amount mismatch — same vendor and invoice, different amount

• In tracker, not paid — invoiced in the tracker, no corresponding bank debit

• Paid, not in tracker — money left the account with no tracker entry

It then layers two independent flags on top, off to the side of the primary buckets:

• Returned / reversed — a bank line that looks like a reversal, return, refund, chargeback, NSF, or void

• Incomplete vendor records — a tracker row missing a vendor name, invoice number, amount, or due date

Vendor names are matched fuzzily, because bank descriptions are truncated, upper-cased, and suffixed with reference numbers. Exact-match reconciliation fails on real data.

Architecture

flowchart LR
    A[Payment tracker CSV] --> C[MCP Server]
    B[Bank export CSV] --> C
    C -->|load_tracker| D[Normalised tracker rows]
    C -->|load_bank_export| E[Normalised bank rows]
    D --> F[Fuzzy vendor match<br/>+ amount compare]
    E --> F
    F --> G[Categorised discrepancy report]
    G --> H[Claude]

The server does the deterministic work — parsing, normalising, matching — and leaves interpretation to the model. Reconciliation logic that decides whether $4,410.00 and $4,410 are the same number should not be probabilistic.

load_tracker and load_bank_export each hold their parsed rows in session state, so the normal flow is load → load → reconcile with no further arguments — reconcile reads whatever was last loaded. (You can still pass trackerPath/bankPath to reconcile to do it in a single call.) This state lives in the running process, not on disk; it does not survive a restart.

All diagnostic logging goes to stderr, never stdout, so it can never corrupt the JSON-RPC message stream the stdio transport carries on stdout.

Design decisions

Fuzzy matching over exact keys. Bank descriptions are not clean. Normalising case, stripping legal suffixes and payment-rail noise (inc, llc, ach, wire, payment), then scoring similarity catches the rows an exact join drops — and it matches on the numeric core of an invoice reference, so tracker invoice INI-4471 still ties to bank reference 4471 even when the bank prints the vendor as "INITEK SFTWR".

Amount tolerance is configurable, and defaults to one cent (0.01). The default absorbs sub-cent floating-point and rounding artifacts while still surfacing anything larger — a fee or an FX spread shows up as an amount mismatch for the caller to judge rather than being silently swallowed. Set it to 0 for exact-only, or raise it if small differences are expected. The vendor-name match threshold (nameThreshold, default 0.6) is configurable the same way.

Returned payments are their own category, not a mismatch. A reversal looks like a duplicate to a naive matcher. Treating it as its own case is the difference between a report someone acts on and one they ignore.

Nothing is written back. The server reads and reports. Anything that mutates a payment record belongs behind a human approval step.

No runtime dependencies beyond the MCP SDK. The server is built on @modelcontextprotocol/sdk (v1.30) over the stdio transport, and the CSV parser is written from scratch — it handles quoted fields, embedded commas and newlines, and accounting formats like $1,234.50 and (123.45) — so there is no third-party CSV library to trust or keep patched.

Setup

npm install
npm start

Add to your MCP client config:

{
  "mcpServers": {
    "payment-reconciliation": {
      "command": "node",
      "args": ["/absolute/path/to/payment-reconciliation-mcp/src/index.js"]
    }
  }
}

Try it

/samples contains fake tracker and bank export files with discrepancies deliberately planted — a mismatched amount, an unrecorded debit, a reversal, and vendors whose names differ across the two files.

Reconcile samples/payment_tracker.csv against samples/bank_export.csv

Expected output — 13 tracker rows against 13 bank rows:

Summary
  matched               7
  amount mismatches     2
  in tracker, not paid  4
  paid, not in tracker  2
  returned / reversed   2   (flagged separately)
  incomplete records    2   (flagged separately)

Matched (7)
  Acme Office Supplies Inc, Northwind Traders LLC, Umbrella Logistics Ltd,
  Wonka Packaging Co, Wayne Facilities Management, Cyberdyne Systems,
  Initech Software  (tracker INI-4471 ↔ bank ref 4471, "INITEK SFTWR")

Amount mismatches (2)
  Globex Corporation      tracker 975.00   bank 985.00    (+10.00)
  Hooli Cloud Services    tracker 8990.00  bank 8900.00   (-90.00)

In tracker, not paid (4)
  Stark Industrial Supply, Soylent Foods Group, Pied Piper Data, Vandelay Imports

Paid, not in tracker (2)
  OSCORP INDUSTRIES (OSC-0012), ZOOMINFO DATA (ZI-5560)

Returned / reversed (2)
  Vandelay Imports (VAN-3311), Soylent Foods Group (SOY-6612, NSF)

Incomplete vendor records (2)
  Cyberdyne Systems (missing invoice), Pied Piper Data (missing amount)

The three primary buckets — matched (7) + amount mismatches (2) + in tracker, not paid (4) — sum to all 13 tracker rows; every invoice is accounted for exactly once. The returned/reversed and incomplete-record lists are orthogonal flags layered on top: Vandelay and Soylent show up as not paid because their only bank line was a reversal, and Cyberdyne is both matched and flagged for a missing invoice number.

Verified

npm test

node:test suite, 4/4 passing — covering amount parsing, name normalisation, fuzzy similarity, and a full reconciliation over the sample fixtures that asserts each bucket and flag lands where expected.

Not in scope

• No bank API integration; this reads exported files on purpose, because that is what finance teams actually have

• No multi-currency handling yet

• No persistence to disk — loaded files are cached in memory for the life of the session and are gone on restart

Why I built it

I run financial and payment operations for US companies from Nairobi, across Bill.com, ACH, checks, and wires. Vendor reconciliation is the task I have done most often by hand and trusted least. This is that task, automated, using the tooling I would reach for at work.

Built with Node and the Model Context Protocol SDK.

License

MIT

Mary Ogola — AI automation and business systems. LinkedIn