Finance MCP Server

A Model Context Protocol (MCP) server that turns a personal-finance SQLite database into a set of typed, schema-validated tools an AI assistant (such as Claude Desktop) can call directly — letting you manage accounts, transactions, budgets, debts, investments, tax estimates, and goals through natural language.

The Model Context Protocol is an open standard that lets AI assistants connect to external tools and data sources through a uniform interface.

This repository is a clean, self-contained reference implementation. It ships with no data and no secrets — just the schema, the tool definitions, and the server scaffolding. Create an empty database, point an MCP client at it, and start talking to your finances.

Why this exists

It is a focused demonstration of how to build a production-shaped MCP server:

• Modular tool registration — each domain (accounts, transactions, tax, …) is a small module exposing a register(server) function.

• Typed, validated inputs — every tool declares its parameters with Zod schemas, so bad input is rejected before it reaches the database.

• A real data layer — better-sqlite3 with parameterized queries, foreign keys, WAL mode, and atomic multi-statement transactions.

• Analytical tools, not just CRUD — e.g. monthly spending rollups, budget progress, a debt-payoff amortization simulator, a tax estimator, and a derived financial-health score.

• Safe external integrations — an example brokerage-sync tool that reads credentials from environment variables / settings (never hard-coded) and writes results inside a single transaction.

Related MCP server: Expense Tracker MCP Server

Tools

Architecture

index.js              # MCP server entry point — registers every tool module over stdio
db.js                 # SQLite connection (better-sqlite3), path from DATABASE_PATH
schema/schema.sql     # Consolidated database schema (no data)
scripts/init-db.js    # Creates an empty database from the schema
lib/
  csv-parser.js       # Tolerant bank-CSV parser (pure, unit-tested)
  tax-calc.js         # Tax-estimation logic (pure, unit-tested)
tools/
  settings.js         # Key-value settings
  accounts.js         # Accounts CRUD
  transactions.js     # Transactions + CSV import
  categories.js       # Categories + categorization rules
  debts.js            # Debts + payoff projection
  budget.js           # Budget rules + progress
  investments.js      # Holdings, investment transactions, snapshots
  tax.js              # Tax records, config, estimate, export
  health.js           # Financial-health score + reminders
  goals.js            # Goals with computed metrics
  actions.js          # Action items for goals
  broker.js           # Example external brokerage sync
test/                 # Unit tests for the pure library functions

Design notes

• Money is stored as integer minor units (e.g. cents) to avoid floating-point errors.

• Every query is parameterized — no string-concatenated SQL with user values.

• Bulk writes (CSV import, brokerage sync) run inside a single transaction so a failure leaves the database unchanged.

• Each tool returns its result as JSON text content, the standard MCP shape.

Getting started

Requires Node.js 18+ (for the global fetch used by the example integration).

git clone <your-fork-url> finance-mcp-server
cd finance-mcp-server
npm install

# Create an empty database at ./data/finance.db
npm run init-db

# (optional) configure environment
cp .env.example .env

# Run the test suite (no database required)
npm test

# Start the server (speaks MCP over stdio)
npm start

Connecting to Claude Desktop

Add the server to your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "finance": {
      "command": "node",
      "args": ["C:/path/to/finance-mcp-server/index.js"],
      "env": {
        "DATABASE_PATH": "C:/path/to/finance-mcp-server/data/finance.db"
      }
    }
  }
}

Restart Claude Desktop. The finance tools will appear and Claude can call them on your behalf — e.g. "Add a $42 grocery expense today" or "How much did I spend on dining last month?". The same server works with any MCP-compatible client over stdio.

Scope & honesty note

This is a portfolio / reference implementation extracted and generalized from a private personal-finance application. It demonstrates the engineering — MCP tool design, schema validation, and a SQLite data layer — and intentionally ships with no data, no credentials, and no jurisdiction-specific business rules.

The sync_brokerage tool is a generic example: it shows the credentials-from-environment + atomic-write pattern but points at a placeholder API. Wire it up to a real provider before using it. The tax estimator is illustrative only and is not tax advice for any country.

License

MIT