Finance Manager MCP

Self-hosted personal finance for MCP clients. Your banks stay read-only (SimpleFIN), your data lives in a local SQLite file you own, and an LLM can only query deterministic totals — it never writes the ledger.

SimpleFIN (read-only)
    → raw_syncs (append-only JSON)
    → truth tables (accounts, transactions, rules, budgets)
    → warm-cache aggregates
    → atomic functions / MCP tools (stdio + gRPC)

Why this shape

• Idempotent ingest — transactions are keyed on the bank-assigned SimpleFIN id. Re-syncing the same dump yields zero net-new rows; identical-looking new charges are never collapsed.
• Deterministic categorization — first-match-wins regex rules. No model in the write path.
• Warm cache — monthly spending, cash flow, net-worth snapshots, and recurring streams persist in SQLite so restarts are instantly warm. Cache is derived; rebuild-cache regenerates it from truth tables.
• Profile UUID namespacing — every write tool requires a profile_id. Multiple profiles never leak into each other.
• Dual transport — stdio for Claude Desktop / Cursor, gRPC via the sibling GRPC-MCP package.

Setup

Python 3.11+.

python -m venv .venv
# Windows: .venv\Scripts\activate
# Unix:    source .venv/bin/activate
pip install -e ".[dev]"
# optional gRPC transport (sibling ../GRPC-MCP)
pip install -e "../GRPC-MCP/python"
pip install -e ".[grpc]"

cp .env.example .env
# paste a Fernet key into FINANCE_ENCRYPTION_KEY
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

finance-mcp init                          # creates data/finance.db + a default profile
finance-mcp profile list                  # copy the profile UUID

Point it at SimpleFIN

From an MCP client, ask to connect a bank. The agent should:

1. Call begin_simplefin_connect (or use prompt connect_simplefin).
2. Show you bridge.simplefin.org — you sign in, connect banks (read-only), copy the one-time setup token.
3. Call claim_connection with that token. The access URL is encrypted at rest.
4. Optionally sync_now on the same profile_id.

CLI still works if you prefer a terminal:

finance-mcp claim-token --token "<setup-token>" --name "My Banks" --profile <PROFILE_UUID>
finance-mcp sync --profile <PROFILE_UUID>

sync is safe to run from Task Scheduler / cron. Overlapping windows do not double-count.

Serve

finance-mcp serve-stdio                   # Claude Desktop / Cursor
finance-mcp serve-grpc --auth bearer      # sibling GRPC-MCP transport
finance-mcp token new --name cursor --profile <PROFILE_UUID>

The bearer token is printed once. gRPC stores only the SHA-256 hash.

Atomic functions

Everything in finance_mcp.api is a plain function. MCP tools are thin wrappers. Import the library without running a server:

from finance_mcp.config import Settings
from finance_mcp.core.db import Database
from finance_mcp import api

db = Database.from_settings(Settings.from_env())
print(api.net_worth(db, profile_id))

Read

list_accounts, get_balances, net_worth, net_worth_history, search_transactions, recent_transactions, spending_by_category, cash_flow, recurring_streams, upcoming_payments, budget_status, list_rules, sync_status, profile_info, list_profiles, begin_simplefin_connect

Write (always require profile_id)

claim_connection, create_rule, update_rule, delete_rule, apply_rules, create_budget, update_budget, delete_budget, sync_now

Tests

The suite is hermetic — synthetic fixtures only, no credentials.

pytest -q

Security

• SimpleFIN access URLs are encrypted with FINANCE_ENCRYPTION_KEY (Fernet). Back the key up.
• gRPC bearer tokens are stored as hashes.
• Read tools open SQLite with mode=ro. Write tools are the only mutation path and are profile-scoped.
• data/ and .env are gitignored.

License

Use as you like for personal self-hosted finance.