EvenKeel MCP — your expense engine, as a standard AI capability

A working Model Context Protocol integration: an MCP server that exposes EvenKeel's expense data and its flagship normalization engine as MCP tools, resources, and prompts — so any MCP-capable AI (Claude Desktop, Claude Code, Cursor, your own agent) can reason about real finances through one standard interface.

It's the textbook MCP use case: take an existing app's logic and re-expose it over a standard protocol — built by reusing EvenKeel's real, unit-tested engine, not reimplementing it. So the numbers an AI gets are byte-for-byte the ones EvenKeel's UI shows.

Brand-new to MCP? Read docs/MCP_EXPLAINED.md (how it works + where it adds value), then docs/GUIDANCE.md (a tour of this code).

flowchart LR
    Host["AI host<br/>(Claude Desktop / Code)"] -->|"MCP over stdio"| Server["evenkeel-mcp"]
    Server --> Engine["EvenKeel's REAL engine<br/>(normalization · insights)"]
    Server --> Data[("EvenKeel backup JSON<br/>(or bundled sample)")]

Quickstart

Requires Node 18+ (built on Node 24). The sibling evenkeel project must sit next to this one — this server imports its engine.

git clone https://github.com/boyukbas/evenkeel.git
git clone https://github.com/boyukbas/evenkeel-mcp.git
(cd evenkeel && npm install)
cd evenkeel-mcp
npm install
npm run gen:sample    # bake data/sample-backup.json from EvenKeel's real seed (once)
npm run demo          # launch the server + an MCP client; watch every primitive round-trip

npm run demo is the integration test: it spawns the server as a stdio subprocess, does the MCP handshake, then lists and calls every tool, reads the resources, and fetches a prompt — printing the results.

Point it at your own money: export a backup from EvenKeel (Settings → Export backup (.json)) and set EVENKEEL_BACKUP=path\to\backup.json. With nothing set, it serves a realistic bundled sample so it runs with zero setup.

Related MCP server: dingdawg-finance-agent

What you can ask it

Once wired into a host (see examples/ and docs/GUIDANCE.md):

"What do I actually spend per month vs. my smoothed baseline?" → get_monthly_spending "Audit my subscriptions." → audit_subscriptions "Where can I save money?" → find_savings "Review my finances." → the review_my_finances prompt

Tests

npm test         # 8 behaviour tests pinning the normalization, audit, savings & insights
npm run typecheck

The tests run EvenKeel's real engine, so green is genuine evidence the flagship math is correct end to end (e.g. a $1,320/yr premium normalizes to exactly $110/mo; a $300 quarterly bill to $100/mo).

Project structure

evenkeel-mcp/
├── src/
│   ├── server.ts       # the MCP server (tools + resources + prompts, stdio transport)
│   ├── evenkeel.ts     # domain layer: Dataset → the answers tools return (wraps EvenKeel's engine)
│   ├── dataset.ts      # load + validate an EvenKeel backup (or the bundled sample)
│   └── types.ts        # shared types (EvenKeel entities + BackupFile)
├── scripts/
│   ├── generate-sample.ts  # dev-only: EvenKeel's real seed → data/sample-backup.json
│   └── demo-client.ts      # an MCP client that drives the server (the integration test)
├── tests/evenkeel.test.ts
├── data/sample-backup.json # committed so the server runs with zero setup
├── examples/               # ready-to-paste Claude Desktop / Claude Code configs
└── docs/                   # MCP_EXPLAINED.md (concepts) · GUIDANCE.md (code tour)

What this demonstrates

• All three MCP server primitives — tools (model-controlled actions), resources (app-controlled data, static and templated), prompts (user-controlled templates).

• The stdio transport and the real client↔server handshake, both ends written against the official @modelcontextprotocol/sdk.

• Typed I/O — Zod input schemas on every tool and a validated outputSchema with machine-readable structuredContent.

• Integration over reimplementation — the server reuses EvenKeel's pure engine via a path alias, with the browser-only Dexie layer isolated to a build-time script so the server stays headless.

• Production-minded seams — pluggable data source (sample ↔ real backup), the stdout/stderr stdio discipline, behaviour tests, and a one-command demo.

License / status

Personal learning project. Local-first, like EvenKeel — nothing leaves your machine; the server only reads a backup file you point it at.