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.

Tools

Tool	Description	Key inputs
get_setting / set_setting / get_all_settings	Read/write key-value app settings	key, value
get_accounts / get_account	List accounts or fetch one	id
create_account / delete_account	Add or remove an account	name, type, bank, balance, creditLimit
get_transactions	Query transactions with filters & paging	accountId, categoryId, fromDate, toDate, search, isBusiness, limit, offset
create_transaction / delete_transaction	Add or remove a transaction	accountId, date, amount, currency, categoryId
update_transaction_category	Recategorize a transaction	id, categoryId, isBusiness
get_monthly_spending	Spending grouped by category for a month	year, month
import_csv	Import a bank-export CSV with auto-categorization & dedup	filePath, accountId
get_categories / create_category / update_category / delete_category	Manage categories	name, type, icon, color, isTaxDeductible
get_categorization_rules / create_categorization_rule / delete_categorization_rule	Regex rules that auto-tag imported transactions	pattern, categoryId, isBusiness
get_debts / create_debt / delete_debt	Manage debts	name, type, originalBalance, currentBalance, interestRate
get_payoff_projection	Simulate months & interest to pay off a debt	debtId, extraMonthly
get_budget_rules / set_budget_rule / delete_budget_rule	Per-category monthly budget limits	categoryId, monthlyLimit, alertThreshold
get_budget_progress	Spend-vs-limit progress for a month	year, month
get_holdings / create_holding / update_holding_value / delete_holding	Manage investment holdings	name, type, units, currentValue
add_investment_transaction / get_holding_transactions	Record & list buy/sell/dividend/fee events	holdingId, type, units, pricePerUnit
get_portfolio_snapshots / record_portfolio_snapshot	Track portfolio value over time	—
get_tax_estimate	Estimate tax burden for a year	year
get_tax_config / update_tax_config	Per-year tax rule parameters	year, key, value
add_tax_record	Record an income/expense/deduction item	year, type, amount
export_tax_csv	Export business transactions as CSV	year
get_health_score	Derived 0–10 financial-health score	—
check_payment_reminders	Upcoming debt payments due soon	—
get_goals / get_goal / create_goal / update_goal / delete_goal	Financial goals with live computed metrics	title, type, targetValue, metric
get_actions / create_action / update_action / toggle_action / delete_action	Action items attached to goals	goalId, title, dueDate
sync_brokerage	Example: sync holdings from an external brokerage API	— (credentials from env/settings)
get_sync_history	Recent external-sync log entries	source

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