personal-finance-mcp
This is a self-hosted, read-only MCP server that connects to your financial accounts via Plaid, enabling you to query your finances in natural language through an MCP client like Claude Code.
list_accounts: List every account across all linked banks with their balances.get_balances: Retrieve live current and available balances, optionally filtered by specific account IDs.get_transactions: Fetch transactions within a date range (up to ~2 years back), optionally filtered by account.search_transactions: Keyword search across merchant names, transaction names, and counterparty names within a date range.get_recurring_transactions: Identify recurring inflow and outflow streams (e.g., subscriptions, payroll).get_liabilities: View credit card, student loan, and mortgage details including APRs and payment information.get_investment_holdings: See current investment positions with ticker symbols, security names, and metadata.get_investment_transactions: Retrieve buy/sell/dividend history within a date range, joined with security metadata.get_institutions_status: Monitor the health of each linked financial institution, surfacing re-authentication needs or connectivity issues.
Provides read-only access to Chase bank accounts, including balances, transactions, and liabilities via the Plaid API.
personal-finance-mcp
Unofficial. This project is not affiliated with, endorsed by, or sponsored by Plaid Inc. "Plaid" is a trademark of Plaid Inc. This is a self-hosted client that talks to Plaid's API using credentials you supply.
A self-hosted, read-only MCP server that connects your banks, credit cards, loans, and brokerage accounts (via Plaid) to an MCP client like Claude Code. Ask questions about your own finances in plain English — no third-party aggregator (Monarch, Mint, etc.) involved.
What you can ask
"What's my total balance across all accounts?"
"Show me transactions over $100 in the last 30 days."
"Which subscriptions am I still paying for?"
"How much did I spend on groceries last month?"
"Any bank that needs re-authentication?"
Example session (illustrative):
you : What did I spend on groceries last month?
claude : [calls get_transactions]
$487.23 across 14 transactions. Top merchants:
Whole Foods ($198), Trader Joe's ($156), Safeway ($89).
you : Any subscriptions I'm still paying for?
claude : [calls get_recurring_transactions]
7 active recurring outflows totaling $142/mo:
Netflix ($15.99), Spotify ($11.99), NYT ($4), ...Related MCP server: FinLynq
Tools
All 9 tools are read-only. Each returns {<data>: [...], "warnings": [...]} so one broken bank doesn't break the whole query.
Tool | What it does |
| Every account across every linked bank, with balances |
| Live current + available balances (optionally filtered by account) |
| Transactions in a date range (up to 2 years back) |
| Keyword search across merchant / name / counterparty |
| Detected recurring inflow + outflow streams |
| Credit cards, student loans, mortgages with APRs and payment details |
| Current holdings with symbol + security metadata |
| Buy / sell / dividend history in a date range |
| Health of each linked bank (surfaces re-auth needs) |
Quickstart
Requires Python 3.11+, a Plaid account (free Trial plan), and an MCP client.
1. Plaid setup
Sign up at https://dashboard.plaid.com/signup → choose the Trial plan (free, 10 Items).
Team Settings → Products: enable Transactions, Liabilities, Investments.
Team Settings → API: copy your
client_idand productionsecret.
2. Install
git clone https://github.com/JosueM1109/personal-finance-mcp.git
cd personal-finance-mcp
python3.11 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # then fill in PLAID_CLIENT_ID and PLAID_SECRET
pytest -v # sanity check3. Link each bank
Run once per bank you want to connect:
uvicorn link_helper:app --port 8765Open http://localhost:8765, click Link a bank, complete Plaid Link. The terminal prints a line like PLAID_TOKEN_CHASE=access-prod-xxx... — paste it into .env and repeat for each bank.
4. Run it
python server.py # serves on http://localhost:8000/mcp5. Add to Claude Code
claude mcp add --transport http personal-finance http://localhost:8000/mcpTry "list my accounts" to confirm.
Deployment
For a deployment you can use from anywhere:
Docker (included):
docker build -t personal-finance-mcp . && docker run --rm -p 8000:8000 --env-file .env personal-finance-mcpAny Python host (Fly.io, Railway, Raspberry Pi + Tailscale, a VPS): set the env vars from
.env.example, expose/mcpover HTTPS, gate it with auth.Prefect Horizon (what the author uses — $0 recurring cost): see docs/DEPLOYMENT.md for the full walkthrough.
Gate the endpoint. An exposed MCP endpoint with your tokens leaks every linked account. Use OAuth 2.1, Cloudflare Access, or bind to a private network only.
Security
Single-tenant. One deployment per person. Don't share.
Read-only. No tool mutates state at any institution. Don't add any that do.
Tokens live in env vars, never on disk.
.envis gitignored.You own Plaid compliance. You're the Plaid customer under your own account.
Before each deploy:
.envnever committed:git log --all -- .envreturns nothingNo real tokens in history:
git log -S'access-prod-' --allreturns only placeholdersAuth gate in front of the MCP endpoint (or localhost-only)
HORIZON=1(or similar) set in deployment env, blockinglink_helper.pythereCheck
get_institutions_status()every few weeks for re-auth needs
Troubleshooting
Tool returns empty despite real data. Plaid products weren't enabled when you linked the bank. Re-link with Transactions + Liabilities + Investments active. The tool surfaces PRODUCTS_NOT_SUPPORTED in warnings when this is the cause.
get_institutions_status() shows re_auth_required. The bank's Plaid session expired. Run link_helper.py in update mode — your existing access token stays the same. See docs/DEPLOYMENT.md.
Plaid Link shows a bank as "unsupported" (common with Amex). Usually an INSTITUTION_REGISTRATION_REQUIRED issue — OAuth banks need per-institution registration in the Plaid dashboard first. See docs/TROUBLESHOOTING.md.
More issues: docs/TROUBLESHOOTING.md.
Architecture
server.py — FastMCP server, 9 read-only tools.
plaid_client.py — Plaid SDK wrapper:
SecretStrtoken redaction, 5-minute per-Item health cache, response shaping, structured error mapping.link_helper.py — Local-only FastAPI app for Plaid Link. Refuses to run if
HORIZON=1is set.
Deeper dive (including why /transactions/get over /transactions/sync): docs/ARCHITECTURE.md.
Contributing
See CONTRIBUTING.md. Scope is deliberately narrow: read-only, single-tenant, Plaid-backed.
Available Tools
9 toolsget_balancesGet BalancesARead-only
Get live current + available balances for accounts.
Inputs: account_ids. Returns: object
get_institutions_statusGet Institutions StatusARead-only
Return health status for every linked Item/institution.
No additional network calls beyond what all_items already makes (it
uses the 5-minute health cache). Enumerates linked Items and reports their
current health status.
Returns: {"items": [{"env_key", "institution", "institution_id", "status", "reason"}, ...]}
Inputs: no named parameters. Returns: object
get_investment_holdingsGet Investment HoldingsARead-only
Return investment holdings with security metadata across all linked Items.
Joins holdings with the securities list returned in the same response to provide symbol, name, and security type. Adds institution to each holding.
Returns: {"holdings": [...], "warnings": [...]}
Inputs: no named parameters. Returns: object
get_investment_transactionsGet Investment TransactionsARead-only
Fetch investment transactions in [start_date, end_date] across all healthy Items.
Dates are ISO YYYY-MM-DD. Uses offset pagination (count=500 per page). If start_date is older than ~2 years before end_date, the window is clipped and a warning is emitted. Each transaction is joined with security metadata (ticker symbol, name) from the same response.
Returns: {"investment_transactions": [...], "warnings": [...]}
Inputs: start_date (required), end_date (required). Returns: object
get_liabilitiesGet LiabilitiesARead-only
Return credit, student-loan, and mortgage liability details across all linked Items.
For Items where the liabilities product is not enabled, a per-Item warning with code PRODUCTS_NOT_SUPPORTED is emitted instead of failing the call.
Returns: {"credit": [...], "student": [...], "mortgage": [...], "warnings": [...]}
Inputs: no named parameters. Returns: object
get_recurring_transactionsGet Recurring TransactionsARead-only
Return recurring inflow and outflow streams across all linked Items.
Calls /accounts/get first per Item to collect account IDs (required by /transactions/recurring/get), then fetches recurring streams and shapes them into unified inflows/outflows lists.
Returns: {"inflows": [...], "outflows": [...], "warnings": [...]}
Inputs: no named parameters. Returns: object
get_transactionsGet TransactionsARead-only
Fetch transactions in [start_date, end_date] across all healthy Items.
Dates are ISO YYYY-MM-DD. Uses Plaid /transactions/get with offset pagination (count=500 per page). If start_date is older than ~2 years before end_date, the window is clipped and a warning is emitted.
Inputs: start_date (required), end_date (required), account_ids. Returns: object
list_accountsList AccountsARead-only
List every account across all linked Items, with balances.
Returns: {"accounts": [...], "warnings": [...]}. Warnings describe Items that are unhealthy (re-auth required, etc.) or hit API errors on this call.
Inputs: no named parameters. Returns: object
search_transactionsSearch TransactionsARead-only
Search transactions by keyword across merchant, name, and counterparty names.
Fetches transactions in [start_date, end_date] and filters them with a case-insensitive substring match against:
merchant_namenamecounterparties[].name
The match is performed on the raw Plaid payload before shaping so that
counterparty names (which are dropped by shape_transaction) are
searchable. Dates are ISO YYYY-MM-DD. The window is clipped to ~2 years
and a WINDOW_CLIPPED warning is emitted when applicable.
Returns: {"transactions": [...], "warnings": [...]}
Inputs: query (required), start_date (required), end_date (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a distinct aspect of personal finance data (balances, transactions, investments, liabilities, etc.), with clear boundaries. There is no overlap in functionality; even transaction-related tools distinguish between regular, investment, recurring, and search operations.
All tools follow a consistent verb_noun pattern in snake_case, primarily using 'get_' for retrieval and 'list_' for accounts, which is predictable and unambiguous.
With 9 tools, the server is well-scoped for a personal finance data aggregator. Each tool serves a clear purpose without redundancy, covering core financial data retrieval needs.
The tool surface covers most essential read operations for personal finance: accounts, balances, transactions (multiple types), liabilities, and holdings. Minor gaps such as lack of categorization or income/expense summaries are acceptable for a focused data provider.
Maintenance
Related MCP Connectors
Read-only finance MCP server. Connects your banks, cards, payment apps, books and payroll into one ledger for your AI. Can't move money. Open source (AGPL-3.0), free during beta.
Query your real net worth, spending, transactions, budgets and portfolio from any MCP client.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Read-only bank & investment accounts via Plaid: balances, holdings, transactions, SQL analytics.
Related MCP Servers
- AlicenseAqualityDmaintenanceA read-only MCP server that enables users to analyze their real bank, credit card, loan, and brokerage data through Plaid. It provides financial analysis tools for transactions, balances, investments, liabilities, and debt while keeping all access tokens and data locally stored.24MIT
- AlicenseCqualityAmaintenanceopen-source personal finance app with a first-party MCP server. 91 HTTP tools (OAuth 2.1 + DCR) and 87 stdio tools cover transactions, budgets, accounts, portfolio analytics, FX conversion, loans, subscriptions, goals, importers, and rules. Users self-host with Docker + PostgreSQL or use the managed cloud8932AGPL 3.0
- AlicenseNot gradedqualityDmaintenanceA local MCP server that provides read-only SQL access to financial accounts via Plaid, enabling natural language queries about transactions, balances, and holdings.MIT
- FlicenseNot gradedqualityDmaintenanceEnables self-hosted personal finance management for MCP clients by connecting read-only bank accounts via SimpleFIN, syncing transactions into a local SQLite database, and exposing tools to query balances, spending, budgets, cash flow, and net worth.-