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.

Related MCP server: personal-finance-mcp

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

The interactive path is the same from a terminal or an MCP client.

finance-mcp setup                  # prints the Bridge URL, waits for the pasted token, claims, syncs
finance-mcp setup --dry-run        # print the dialogue only (no claim)
finance-mcp setup --token "<setup-token>"

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.

scripts/verify exercises that dialogue with a scripted paste (no TTY, no network). finance-mcp verify --setup-only runs just those tests.

The older one-shot CLI still works:

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

Hermetic tests use synthetic fixtures only (no credentials, no network):

pytest -q -m "not live"
# or the wrapper, which is what to run as we develop:
python scripts/verify              # setup dialogue + hermetic suite
python scripts/verify --setup-only # interactive setup path only
# same thing via the CLI:
finance-mcp verify
finance-mcp setup --dry-run        # print the live dialogue without claiming

Live SimpleFIN checks (claim token → fetch → ingest → idempotent re-sync → read APIs) are opt-in. Put a one-time setup token or an already-claimed access URL in .env:

# SIMPLEFIN_SETUP_TOKEN=<paste setup token>
# or SIMPLEFIN_ACCESS_URL=https://user:pass@bridge…/simplefin
python scripts/verify --live

The first successful claim writes the access URL to gitignored data/.simplefin_access_url so later --live runs reuse it. The token itself is never committed.

pytest -q -m live          # live tests only; skipped if no credentials

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.