Skip to content

About

Local SimpleFIN-backed MCP server that gives GitHub Copilot read access to your bank & credit-card transactions. Privacy-first: data stays on your machine.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

finance-mcp

Local, privacy-first access to your bank and credit-card transactions for Copilot, backed by SimpleFIN. It pulls transactions from your institutions into a normalized on-disk cache and exposes them to Copilot as an MCP server. Nothing leaves your machine except the single HTTPS call to SimpleFIN — no third-party SaaS sees your data, and no fake/sample data is ever shown.

Why SimpleFIN

All of these institutions are supported by SimpleFIN (verified against its live institution search): Target credit card, Nordstrom Card Services, Amazon Chase card (via Chase Bank), Fidelity credit card, Fidelity NetBenefits (via Fidelity Investments), Charles Schwab, and Cyprus Credit Union. SimpleFIN costs ~$15/yr flat with no per-account billing, and you hold the access token.

Security model

The SimpleFIN access URL embeds Basic-Auth credentials that can read your transactions. It is therefore stored outside this project directory (this repo may live in a synced folder like Dropbox):

  • Access URL + transaction cache live in ~/.finance-mcp/ (dir 0700, files 0600).
  • Override the location with FINANCE_MCP_HOME.
  • The access URL may instead be supplied via the SIMPLEFIN_ACCESS_URL env var (takes precedence over the saved file), so it never has to touch disk.

Setup

  1. Get a SimpleFIN setup token: sign up at https://bridge.simplefin.org/ and generate one (it is a base64 string).

  2. Claim it (one-time — the token dies after a successful claim):

    uv run finance-mcp claim            # prompts for the token
    # or: uv run finance-mcp claim <SETUP_TOKEN>

    The resulting access URL is saved to ~/.finance-mcp/access_url (mode 0600).

  3. Pull your transactions into the cache:

    uv run finance-mcp sync --days 120

Crew pockets (optional)

The direct Crew connector adds live pocket balances, pocket activity, and transfer history that the combined SimpleFIN account does not contain. It does not move money or change the SimpleFIN archive, budgets, or scheduler.

Run sign-in yourself in an interactive terminal:

uv run finance-mcp crew login
uv run finance-mcp crew pockets
uv run finance-mcp crew activity --account ACCOUNT_ID --pocket POCKET_ID
uv run finance-mcp crew transfers

Phone/email and verification codes use hidden input. Do not send codes to Copilot. The private session is saved outside the checkout under FINANCE_MCP_HOME (default ~/.finance-mcp/crew_session.json, mode 0600). Read-only describes this connector, not the authority of Crew's session token.

Copilot uses crew_pockets, crew_pocket_activity, and crew_transfers. Activity and transfers return one page of 100 records; pass end_cursor as after when has_next_page is true. A page is not complete history. Amounts are integer cents, null amounts are unknown, and retrieved_at is retrieval time rather than the bank's balance timestamp. Requests time out after 30 seconds. There is no stale cache fallback.

crew status checks local session presence without claiming authentication. crew disconnect removes only the local session; it does not revoke the upstream token. Expired sessions require attended sign-in again. The documented consumer API may change; live pocket and internal-transfer coverage must be verified after sign-in.

CLI

uv run finance-mcp accounts                          # balances per account
uv run finance-mcp transactions --search grocery     # search the full archive
uv run finance-mcp transactions --start 2026-01-01 --account <id> --json
uv run finance-mcp summary --group-by month          # inflow/outflow aggregation
uv run finance-mcp summary                            # defaults to group-by category, excludes transfers
uv run finance-mcp networth                          # net-worth total per snapshot date
uv run finance-mcp stats                             # archive size + date coverage
uv run finance-mcp categorize                        # seed default rules + show coverage
uv run finance-mcp uncategorized                     # top still-uncategorized merchants
uv run finance-mcp rules list                        # show categorization rules
uv run finance-mcp rules add --pattern "trader joe" --category Groceries
uv run finance-mcp rules rm --rule-id <id>           # remove a rule
uv run finance-mcp set-category <txn_id> Travel      # pin one transaction's category
uv run finance-mcp sync --days 120                    # refresh from SimpleFIN
uv run finance-mcp subscriptions detect               # save recurring charges as a tracked list
uv run finance-mcp subscriptions                      # audit: did tracked bills post? + new candidates
uv run finance-mcp subscriptions mark --name Sketch --lifecycle canceled --effective 2026-04-01
uv run finance-mcp web                                # local read-only review UI in the browser

subscriptions detect scans the archive for recurring monthly charges and saves them into the budget config so your subscriptions become a durable list rather than something re-inferred on every run; it is idempotent and skips merchants already tracked. subscriptions (audit) then reports any tracked bill that did not post in its cycle — a possible billing problem or cancellation — and surfaces untracked recurring merchants as candidates to add. A saved subscription needs no envelope budget: a match keyword pins it to its merchant. Detection is a heuristic starting point — review the saved list and remove any false positives.

subscriptions mark is the cancellation watch: after you cancel (or try to cancel) a subscription, mark it canceling (attempted, unconfirmed) or canceled (confirmed) with the effective date. The audit then stops reporting its expected charges as missing — the absence is what you wanted — and instead warns you if a charge posts on or after that date, so a cancellation that didn't take is surfaced rather than silently billed. --lifecycle active reactivates a bill. Recurring bills and subscriptions are one list: anything in the budget's recurring calendar can be watched this way.

SimpleFIN caps a request at 90 days and expects <=24 requests/day, so sync chunks long ranges into <=89-day windows and you should rely on the archive for day-to-day queries rather than re-syncing constantly. Any SimpleFIN warnings or errors (errors/errlist) are always surfaced.

Web UI (review in the browser)

finance-mcp web starts a local, read-only web UI for reviewing the archive and the budgeting reports without leaving the terminal-driven workflow:

uv run finance-mcp web                 # serves http://127.0.0.1:8765/
uv run finance-mcp web --port 9000     # pick a different port

It binds to 127.0.0.1 only by default because it serves private financial data (override with --host only if you understand the exposure). The request Host header is always checked against an allowlist, so a 127.0.0.1 bind is not defeated by DNS-rebinding; to reach a non-loopback or wildcard bind from another device, name that device-facing host with --allow-host (every other Host is refused). Every page is backed by the same functions the MCP server exposes, so the browser view and Copilot see identical data, and nothing is mutated — there is no sync or confirm action in the UI. Tabs cover accounts, transactions, spending, net worth, transfers, and the burn-down / forecast / allocation / subscription reports; each view also exposes the raw JSON it rendered.

Local archive (multi-year history)

Every sync does two things locally, both in ~/.finance-mcp/ (mode 0600):

  • updates cache.json — the latest normalized snapshot, and
  • folds the data into archive.db, a SQLite database that is the durable, searchable, multi-year history.

The archive is append-only: transactions are upserted by their stable SimpleFIN id (a pending charge is later promoted to posted without duplicating), first_seen is preserved, and nothing is ever deleted — so a transaction stays in the archive even after it ages out of SimpleFIN's rolling window. Each sync also records a balance snapshot per account, which is what powers networth / net_worth_history trends over time.

SimpleFIN read commands and MCP tools serve from archive.db (falling back to cache.json only before the first sync on this version). You can also query it with any SQLite tool:

sqlite3 ~/.finance-mcp/archive.db \
  "SELECT posted, amount, description FROM transactions ORDER BY posted_ts DESC LIMIT 10;"

MCP server (use it from Copilot)

The server runs over stdio and exposes these tools:

Tool Network? Purpose
list_accounts no accounts + balances + institution
account_balances no just balances and as-of dates
get_transactions no filter by date / account / search / amount (includes category)
spending_summary no inflow/outflow grouped by category, account, org, or month
categorization_status no category coverage + spend-by-category breakdown
list_category_rules no the active substring → category rules
add_category_rule no add a rule (optionally flag matches as transfers)
remove_category_rule no delete a rule by id
set_transaction_category no pin one transaction's category (survives sync)
net_worth_history no total balance per snapshot date (net-worth trend)
archive_stats no archive size + earliest/latest transaction
sync_now yes refresh the cache + archive from SimpleFIN

Install for others (no clone needed)

With uv installed, you can claim/sync and run the server straight from this repo — uvx fetches and builds it on demand:

# one-time claim + first sync
uvx --from git+https://github.com/dfrysinger/finance-mcp finance-mcp claim
uvx --from git+https://github.com/dfrysinger/finance-mcp finance-mcp sync --days 120

Then register it with Copilot CLI by adding this to ~/.copilot/mcp-config.json under mcpServers (or run /mcp in Copilot to manage):

{
  "mcpServers": {
    "finance": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/dfrysinger/finance-mcp",
        "finance-mcp-server"
      ],
      "tools": ["*"]
    }
  }
}

Local checkout alternative

If you cloned the repo and prefer running from the working tree:

{
  "mcpServers": {
    "finance": {
      "command": "uv",
      "args": ["--directory", "<ABSOLUTE_PATH_TO>/finance-mcp", "run", "finance-mcp-server"],
      "tools": ["*"]
    }
  }
}

get_transactions/spending_summary serve the durable archive (archive.db), which sync (CLI) or sync_now keeps up to date.

Notes / limitations

  • SimpleFIN does not provide spending categories, so categories are assigned locally by a rule engine (case-insensitive substring match on description/payee) plus per-transaction manual overrides — nothing is guessed from outside your data. Internal movements (transfers, card payments, P2P) are flagged so honest spend totals exclude them; pass --include-transfers / include_transfers=true to count them.
  • Amounts are signed: negative = money out. Use max_amount=0 for spending-only, min_amount=0 for income-only.

Development

uv run pytest -q

Verified end-to-end against SimpleFIN's public demo dataset (claim → fetch → normalize → cache → query, plus an MCP stdio round-trip).

About

Local SimpleFIN-backed MCP server that gives GitHub Copilot read access to your bank & credit-card transactions. Privacy-first: data stays on your machine.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages