# 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.

## What it does

Exposes three tools over MCP:

| Tool | Purpose |
|---|---|
| `load_tracker` | Parses a payment tracker CSV (vendor, invoice, amount, due date, status) |
| `load_bank_export` | Parses a bank export CSV (date, description, amount, reference) |
| `reconcile` | Matches the two and returns categorised discrepancies |

`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

```mermaid
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

```bash
npm install
npm start
```

Add to your MCP client config:

```json
{
  "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

```bash
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](https://www.linkedin.com/in/mogola/)