finance-mcp-server – Personal Finance as an AI Tool Surface

Challenge

Consumer finance apps answer the questions they were designed to answer. The moment you want something slightly off-script — how much a specific merchant has cost you over a year, whether a subscription quietly raised its price, what happens to your balance in thirty days if nothing changes — you are exporting a CSV and building a spreadsheet.

Handing that data to a general-purpose AI would answer the questions, but it means uploading a complete record of where you go, what you buy, and what you owe. For financial data specifically, that trade is not worth making. The interesting design problem was whether you could get the flexibility of natural-language querying while the data itself stays put.

Solution

Model Context Protocol inverts the usual arrangement. Instead of sending data to a model, you expose a set of tools the model may call, and the model asks for exactly what it needs. The database stays local; only the answer to the question you asked ever leaves.

• Fifteen tools covering the real question space. Transaction search, spending by category, subscription detection with price-hike flags, merchant history, an N-day cash-flow forecast that marks the projected low point, and an avalanche-versus-snowball debt payoff simulation.
• A pure analytics core, deliberately isolated. The calculation logic is dependency-free TypeScript in its own module, kept separate from both the MCP protocol layer and the storage layer. Nothing in the math knows it is being called by an AI, which means the same core can back a normal application later without being rewritten.
• Idempotent imports. Rows dedupe on a stable hash, so re-importing an updated export adds only genuinely new transactions. Import twice, get the same database — a property that matters more than it sounds when the alternative is silently doubled spending totals.
• Live balances without a broker in the middle. An optional read-only bank aggregation link syncs balances and new transactions. The access credential is claimed into local storage and never transits the chat.
• A rules engine for the messy part. Live-synced transactions arrive as raw bank descriptors and land uncategorized. Rather than a settings screen, categorization is conversational — describe the rule, and it recategorizes every past and future match.
• A glanceable local dashboard. A bundled offline HUD renders net worth, category spending, subscription flags, and the cash-flow projection. No CDN, no external calls, localhost only.

Outcome

The project is public under an MIT license, and it is the thing I point at when someone asks what "builds AI tooling" actually means in practice.

• 15 MCP tools across import, analysis, forecasting, and account sync
• Layered architecture — pure core, storage, and protocol as separate concerns
• Local-first by construction: transaction data is gitignored, never committed, and never transmitted; the documentation screenshot is rendered from synthetic data specifically so no real history is published

The design lesson that transferred furthest was about tool granularity. Early versions exposed a few flexible tools that could do almost anything, and the model used them unpredictably. Narrower, sharper tools — each one answering a single well-formed question — produced better results than powerful general ones. Designing a tool surface for a language model turns out to be an interface design problem, with the same rules: name things for what the user wants, not for what the system does, and make the right call the obvious one.