io.github.adelaidasofia/finance-mcp

finance-mcp

Local-first personal finance MCP. Aggregates bank, brokerage, credit, and loan accounts via Plaid. Writes balances, holdings, and transactions to your local Obsidian-style markdown vault. Access tokens stay in macOS Keychain. Never sends data anywhere except plaid.com.

What it does

• Link any US bank or brokerage via Plaid (Chase, Citi, Schwab, Discover, Fidelity, Wells Fargo, Bank of America, Capital One, Vanguard, Robinhood, Coinbase, student-loan servicers, 12,000+ institutions total).
• Pull live balances for every account → writes the auto-sync block in your vault's Accounts.md.
• Pull investment holdings with shares, cost basis, current value → writes Investments.md.
• Pull transactions cursor-style (delta only after first sync) → stores in local SQLite.
• Roll up monthly cash flow by category → writes Cash Flow.md.
• Pull liabilities (credit-card APRs, statement balances, student-loan payoff info).
• Audit log every Plaid call and every keychain access.

Why local-first matters

Most personal-finance SaaS (Mint, Copilot, YNAB, Monarch) puts your bank data on their servers and charges you for the privilege. This MCP:

• Runs on your laptop, talks directly to Plaid, writes to your local vault.
• Stores access tokens in macOS Keychain, not env files or any database.
• Never returns access tokens in tool responses — items are referenced by alias (chase, citi, etc.).
• Vault data is plain markdown with inline Dataview fields — your data, your format, queryable forever.

Install

Open Claude Code, paste:

/plugin marketplace add adelaidasofia/finance-mcp
/plugin install finance-mcp@finance-mcp

Requires macOS (for Keychain) and Python 3.11+. After install, set your Plaid credentials in .env at the plugin root (see SETUP.md for the Plaid signup walkthrough).

First-time use

> healthcheck

If it shows blockers, follow them. Once green:

> link_start(institution_alias="chase")

Open the returned link_token in Plaid's Link demo page (paste the token in the field labeled "Link Token", then click "Open Plaid Link"). Complete bank auth in the browser. Copy the public_token from the success page.

> link_complete(institution_alias="chase", public_token="public-sandbox-...")

Repeat for each bank.

> sync_balances
> sync_holdings
> sync_transactions
> rollup_month(month="2026-05")

Your vault's Accounts.md, Investments.md, and Cash Flow.md now have auto-sync blocks with current data. Re-run any time.

Tool surface

Security model

• Plaid access_token lives in macOS Keychain (security CLI), service name finance-mcp, account name = your institution alias.
• Plaid client_id + secret live in .env (chmod 600). Never committed (in .gitignore).
• Transaction history lives in SQLite at ~/.claude/finance-mcp/data.db (not in your vault).
• Vault writes only happen inside the configured FINANCE_MCP_FINANCE_FOLDER. Set to empty string to disable vault writes entirely.
• Audit log records every Plaid call and every keychain operation.
• Tool responses never include raw access tokens.

Plaid environments

• sandbox (default): fake banks, fake credentials (user_good / pass_good). Free forever. Use this first.
• development: real banks, free up to 100 items per Plaid account. Use this for personal accounts.
• production: real banks at scale. Requires a Plaid application + paid plan.

Set via PLAID_ENV in .env. Switch by re-linking all institutions (tokens are environment-bound).

Companion MCPs

• jkoelker/schwab-mcp — Direct Charles Schwab Trader API for options, trade placement, and deep position data beyond what Plaid exposes.
• tomasgesino/schwab-mcp — Schwab wheel-strategy management with dry-run-default trading.

finance-mcp covers Schwab basic balances and holdings via Plaid; the above are the route for Schwab power-user features.

Related MCPs in this family

• apollo-mcp — Apollo.io CRM + outbound sequences.
• slack-mcp — Multi-workspace Slack with draft+confirm safety.
• imessage-mcp — Local iMessage with Whisper voice transcription.
• whatsapp-mcp — WhatsApp via local bridge.
• substack-mcp — Publish posts + Notes, pull analytics.
• parse-mcp — Multi-backend document parsing router.
• graph-query-mcp — Personal knowledge graph queries.

Telemetry

This plugin sends a single anonymous install signal to myceliumai.co the first time it loads in a Claude Code session on a given machine.

What is sent:

• Plugin name (e.g. slack-mcp)
• Plugin version (e.g. 0.1.0)

What is NOT sent:

• No user identifiers, names, emails, tokens, or API keys
• No file paths, message content, or anything from your work
• No IP address is stored after dedup processing

Why: Helps the maintainer know which plugins people actually install, so attention goes to the ones that get used.

Opt out: Set the environment variable MYCELIUM_NO_PING=1 before launching Claude Code. The hook will skip the network call entirely. Already-pinged installs leave a sentinel at ~/.mycelium/onboarded-<plugin> — delete it if you want to reset state.

License

MIT. See LICENSE.

For users who can't use the plugin marketplace yet, the manual flow:

git clone https://github.com/adelaidasofia/finance-mcp ~/.claude/finance-mcp
cd ~/.claude/finance-mcp
pip3 install --break-system-packages -r requirements.txt
cp .env.example .env
chmod 600 .env

Then register with Claude Code by adding to your vault's .mcp.json (project scope) or ~/.claude.json (user scope, via claude mcp add):

"finance": {
  "type": "stdio",
  "command": "python3",
  "args": ["-m", "finance_mcp.server"],
  "env": {
    "PYTHONPATH": "/Users/<you>/.claude/finance-mcp",
    "FINANCE_MCP_VAULT_PATH": "/Users/<you>/Documents/MyVault",
    "FINANCE_MCP_FINANCE_FOLDER": "Finance"
  }
}

Restart Claude Code. Tools appear under mcp__finance__*.

Built by Adelaida Diaz-Roa. Full install or team version at diazroa.com.