Copilot Money MCP
This server lets AI assistants query and, with opt-in modes, manage Copilot Money personal finance data, using local cache reads by default.
Query and search transactions by period/date, category, merchant, amount, account, tag, location, pending status, and special types, with pagination and field selection.
Inspect cache availability, date range, counts, and decode health, and refresh the in-memory cache.
View accounts with balances and net worth summaries, and check institution connection/sync status.
Browse categories as lists, trees, or search results, and review budgets, goals, and goal history.
Analyze recurring charges and subscriptions using pattern detection plus Copilot subscription tracking.
Review investment holdings, price history, stock splits, and daily/weekly/monthly balance history.
Optionally use
--live-readsfor real-time GraphQL reads and--writeto mutate transactions, tags, categories, budgets, recurrings, and splits.
Allows querying and analyzing Amazon purchase transactions from personal finance data, including filtering by merchant and date ranges.
Enables setting up Netflix as a monthly recurring charge and managing subscription data within personal finance tracking.
Provides tools to categorize Uber transactions and analyze transportation spending patterns from personal finance data.
Copilot Money MCP Server
Query and manage your personal finances with AI using local Copilot Money data
Disclaimer
This is an independent, community-driven project and is not affiliated with, endorsed by, or associated with Copilot Money or its parent company in any way. This tool was created by an independent developer to enable AI-powered queries of locally cached data. "Copilot Money" is a trademark of its respective owner.
Copilot Money now has an official MCP server. It is read-only, with write support announced as coming later, and connects to MCP clients over OAuth. If a first-party, read-only integration suits your needs, you should strongly consider using it instead of this community project. Setup instructions: Setting up the MCP.
This project remains useful if you need write tools today (categorize transactions, manage budgets, edit recurrings, etc.) or fully offline cache-mode reads with zero network requests.
Related MCP server: LunchMoney MCP Server
Overview
An MCP server that gives AI assistants access to your Copilot Money personal finance data. It reads from the locally cached Firestore database (LevelDB + Protocol Buffers) on your Mac. Reads are 100% local with zero network requests.
14 cache-mode read tools (or 25 in --live-reads mode: 8 surviving cache + 17 live), plus up to 19 write tools — query and modify transactions, accounts, holdings, balances, categories, recurring charges, budgets, goals, and investment performance. See Tools by Mode below.
Contributors: writes go through an API we don't own. How the repo keeps its model of Copilot's GraphQL surface from silently drifting — the conformance ledger, live smokes, and weekly drift check — is documented in
docs/CONFORMANCE_ARCHITECTURE.md.
Privacy First
We never collect, store, or transmit your data to any server operated by this project — we don't have any. See our Privacy Policy for details.
No analytics, telemetry, or tracking of any kind
Reads are fully local — zero network requests
Open source — verify the code yourself
Heads up about AI providers. While this server itself runs locally and never sends your data to any server operated by this project, the AI assistant you connect it to (Claude, ChatGPT, Gemini, etc.) will see your Copilot Money data as part of answering your questions. That means your financial data will be transmitted to and processed by the provider of whichever model you choose — Anthropic, OpenAI, Google, or another third party — subject to that provider's own privacy policy and data retention terms.
By using this MCP server with a hosted AI model, you are knowingly sharing your financial data with that AI provider. Only use this tool if you are comfortable with that trade-off. If you are not, consider using a fully local model.
Tools by Mode
This server exposes different tools depending on which CLI flags you enable.
Mode | Flag | What it does | Auth | Network | Tools available |
🟢 Default | (none) | Reads from your local LevelDB cache | ❌ None | 🔌 Zero (offline) | 14 cache-mode read + utility tools |
🌐 Live reads |
| Real-time reads via Copilot's GraphQL API; swaps out 6 cache tools and adds 11 live-only ones | 🔒 Browser session | 🌐 HTTPS per request | 25 read tools (8 cache + 17 live) |
✍️ Writes |
| Adds mutation tools (transactions, tags, categories, budgets, recurrings, splits) and turns on | 🔒 Browser session | 🌐 HTTPS per request | +19 write tools, on top of the 25 live read tools |
Passing --write implies --live-reads; you can still pass --live-reads on its own for read-only live access.
📖 See docs/tools-by-mode.md for the full per-tool inventory with status, caveats, and known limitations (goals, stock splits, response-size caps).
⬆️ Upgrading from v2? v3.0.0 changed the shape of read responses — see docs/MIGRATING-v3.md. No tool was renamed or removed; rows got terse and two arguments were retired.
Quick Start
Prerequisites
Node.js 18+ (comes bundled with Claude Desktop)
Copilot Money (macOS App Store version)
Claude Desktop, Cursor, or any MCP-compatible client
For
--live-readsor--writeonly: a supported browser logged in to app.copilot.money — the Chromium family, Firefox, or Safari; see docs/graphql-live-reads.md for the list. The server reuses that session's Firebase refresh token. Without it the server still starts, and the first live or write tool call tells the assistant to log in — log in and retry, no restart needed. Default mode needs nothing — it reads the local cache and makes no network requests.
Installation via Claude Desktop
Download the latest
.mcpbbundle from ReleasesDouble-click the
.mcpbfile to install in Claude DesktopRestart Claude Desktop
Start asking questions about your finances!
Installation via npm
npm install -g copilot-money-mcpThen add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"copilot-money": {
"command": "copilot-money-mcp"
}
}
}Installation for Cursor
Install the package globally:
npm install -g copilot-money-mcpOpen Cursor Settings (
Cmd + ,) > Features > MCP ServersAdd the server configuration:
{ "mcpServers": { "copilot-money": { "command": "copilot-money-mcp" } } }
What You Can Do
Spending Analysis
"How much did I spend on dining out last month?"
"Show me all my Amazon purchases in the last 30 days"
"What are my top 5 spending categories this year?"
Uses get_transactions (or get_transactions_live for fresh data via --live-reads) and get_categories (or get_categories_live), with date ranges, text search, and category filters.
Account Overview
"What's my net worth across all accounts?"
"Show me my checking account balance over the past 6 months, monthly"
"Which bank connections need attention?"
Uses get_accounts (or get_accounts_live for fresh balances via --live-reads), get_balance_history (with optional get_balance_history_live per-account live variant), get_connection_status, and get_networth_live for net-worth-over-time charts.
Investment Portfolio
"What are my current holdings and total returns?"
"Show me the price history for my largest equity holding over the past year"
"What's my current cost basis on META?"
Uses get_holdings (or get_holdings_live for live cost basis), get_investment_prices (or get_investment_prices_live for live per-security price history).
Budgets & Goals
"Am I on track with my budgets this month?"
"How is my emergency fund progressing?"
"Show me my goal history over the past 6 months"
Uses get_budgets (or get_budgets_live via --live-reads), and get_goals / get_goal_history (cache-only — Copilot's GraphQL endpoint doesn't expose goal data).
Subscriptions & Recurring
"What subscriptions am I paying for?"
"How much do I spend on recurring charges per month?"
Uses get_recurring_transactions (or get_recurring_live via --live-reads) and get_upcoming_recurrings_live for next-due unpaid items.
Configuration
Cache TTL
The server caches data in memory for 5 minutes. Configure via environment variable:
# Set cache TTL to 10 minutes
COPILOT_CACHE_TTL_MINUTES=10 copilot-money-mcp
# Disable caching (always reload from disk)
COPILOT_CACHE_TTL_MINUTES=0 copilot-money-mcp
# Write tools resolve account/item ids for a transaction id via a live
# window fetch when the in-memory index (fed by live reads) misses.
# Default window: 13 months. Raise it to edit older transactions:
COPILOT_WRITE_RESOLVE_WINDOW_MONTHS=30 copilot-money-mcp --write
# Write-resolution routing ids (opaque transaction/account/item ids only —
# never amounts or names) persist whenever live reads are enabled (including
# --write mode), keyed by the logged-in account, so cross-session writes
# skip the live window fetch.
# The same switch also disables the persisted split-parent record
# (split-parents.<uid>.jsonl, opaque ids only): delete_transaction then
# remembers a parent split through this server only until it restarts, and
# after a restart relies on the local cache to refuse it (#842).
# Disable both entirely:
COPILOT_DISABLE_PERSISTENT_INDEX=1 copilot-money-mcp --writeYou can also refresh manually using the refresh_database tool.
Decode Timeout
For large databases (500MB+), increase the decode timeout (default: 90 seconds):
# Via environment variable
DECODE_TIMEOUT_MS=600000 copilot-money-mcp
# Via CLI flag
copilot-money-mcp --timeout 600000For databases over 1GB, also increase Node.js memory:
{
"mcpServers": {
"copilot-money": {
"command": "node",
"args": [
"--max-old-space-size=4096",
"/path/to/copilot-money-mcp/dist/cli.js",
"--timeout", "600000"
]
}
}
}Supported Date Periods
The period parameter supports these shortcuts:
this_month last_month last_7_days last_30_days last_90_days ytd this_year last_year
Authentication & Optional Modes
Both --live-reads and --write make authenticated calls to Copilot Money's GraphQL API at app.copilot.money/api/graphql. They require a logged-in browser session against app.copilot.money — the server reads the same Firebase refresh token the web app stores in your browser. Ten browsers are searched — Chrome, Arc, Microsoft Edge, Brave, Vivaldi, Chromium, Opera, Opera GX, Safari, and Firefox — and each Chromium-family browser across every one of its profiles, not just the default one. See PRIVACY.md for exactly which files are read and why the browser-wide Local Storage read is not scoped to Copilot's origin.
On Linux the Linux locations are searched instead: Chrome (~/.config/google-chrome, plus -beta / -unstable), Microsoft Edge (~/.config/microsoft-edge), Brave (~/.config/BraveSoftware/Brave-Browser), Vivaldi (~/.config/vivaldi), Chromium (~/.config/chromium and the snap's ~/snap/chromium/common/chromium), Opera (~/.config/opera), and Firefox (~/.mozilla/firefox, ~/.config/mozilla/firefox where Firefox 147+ creates new profiles when there is no ~/.mozilla, the snap's ~/snap/firefox/common/.mozilla/firefox, and the flatpak's ~/.var/app/org.mozilla.firefox/.mozilla/firefox). The ~/.config locations honour XDG_CONFIG_HOME. Arc, Safari and Opera GX are macOS-only.
Choosing the browser and profile: --browser / --browser-profile
By default the browsers above are tried in that fixed order and the first working session wins. If more than one Copilot account is logged in on the machine — say one person in Brave and another in Chrome — pin the one to use:
Flag | Environment variable | Value |
|
|
|
|
| Chromium family: the profile directory ( |
|
| A custom user-data root that replaces the browser's default locations — for a browser launched with |
Each flag wins over its environment variable. With a browser selected, only that browser (and, with a profile, only that profile) is read — there is no fallback to the others, so the session can never silently come from someone else's browser. If nothing is found, the error names exactly what was searched, e.g. No Copilot Money session found in Brave (profile "Default"). …, and says so when the browser's data directory or the profile does not exist.
A profile name must pick exactly one profile. Display names are not unique, and Microsoft Edge's built-in ones are off by one from its directories (directory Default is shown as "Profile 1", directory Profile 1 as "Profile 2"), so a name that matches one profile's directory and another's display name — or two display names, or two Firefox profiles — is refused, and nothing is searched: --browser-profile "Profile 1" is ambiguous in Microsoft Edge: it matches directory "Profile 1" and the display name of directory "Default". Pick exactly one with --browser-profile "dir:Default" or "dir:Profile 1". Every value the refusal offers selects exactly one profile: a Firefox profile that profiles.ini keeps outside the profiles directory is offered as name: instead, since dir: only sees listed directories, and two Firefox profiles that no name tells apart (the same directory name directly in a --browser-data-dir and under its Profiles/, or two profiles.ini entries with one Name= kept outside the profiles directory) are named by path: select one by dropping --browser-profile and pointing --browser-data-dir at it. The dir: form always names exactly one profile, so on a stock Edge with three or more profiles — where every middle Profile N is both a directory and another profile's display name — every profile stays selectable. A directory whose own display name is the same string is not ambiguous. On Linux, an ambiguity inside any one Chrome channel refuses the whole selection, and the message names that channel's directory.
The selection only applies with --live-reads or --write. There, an unknown browser name, a profile without a browser, a macOS-only browser on Linux, or a bad --browser-data-dir stops the server at startup with an error. In the default cache-only mode no browser is read, so a selection — from flags or from the environment, valid or not — is ignored with a one-line warning on stderr instead of stopping the server.
With --browser-data-dir, only that directory is read — not the browser's default locations and not any other browser. --browser-profile then matches profiles inside it (directory name, Local State display name, Firefox suffix or profiles.ini Name=, with relative Path= entries resolved against the data dir). Pointed at a single Firefox profile, no --browser-profile is needed, and one that names a different profile is refused. The server refuses to start if the path does not exist or is not a directory, if no browser is given, or if the browser is Safari (whose locations are fixed by macOS). If the directory holds no session, the error names it: No Copilot Money session found in Chrome (data dir "/home/me/chrome-profile/Fork-18"). …, and if the path looks like one Chromium profile (it is named Default / Profile N or holds a Preferences file) rather than the user-data root above it, the error says so and suggests the parent plus --browser-profile.
{
"mcpServers": {
"copilot-money": {
"command": "copilot-money-mcp",
"args": ["--live-reads", "--browser", "brave", "--browser-profile", "Default"]
}
}
}Or, equivalently, "env": { "COPILOT_BROWSER": "brave", "COPILOT_BROWSER_PROFILE": "Default" } in the same entry. For a Chrome started with a custom --user-data-dir:
"args": ["--live-reads", "--browser", "chrome", "--browser-data-dir", "/home/me/chrome-profile/Fork-18"]Default mode requires no authentication and makes zero network requests — reads come from the local LevelDB cache.
--live-reads: real-time reads via GraphQL
copilot-money-mcp --live-readsReplaces 6 cache-mode read tools (get_transactions, get_accounts, get_categories, get_budgets, get_recurring_transactions, get_holdings) with live GraphQL-backed equivalents, and adds 11 net-new ones (get_tags_live, get_networth_live, get_upcoming_recurrings_live, get_monthly_spend_live, get_balance_history_live, get_investment_prices_live, refresh_cache, get_investment_allocation_live, get_top_movers_live, get_aggregated_holdings_live, get_investment_balance_live).
Use this when:
You need transactions the macOS app hasn't pre-fetched yet (the auto-fetch window is typically ~30 days; past that, open the app and scroll back to force the cache to populate, or use
--live-readsto query the server directly).You want fresh per-security cost basis or balance-over-time data.
The macOS app hasn't synced recently.
--write: mutations via GraphQL (implies --live-reads)
copilot-money-mcp --writeAdds 19 mutation tools for transactions, tags, categories, recurrings, budgets, and split-transactions. Off by default — the server is read-only unless you opt in.
--write automatically enables --live-reads as well. Write tools resolve transaction metadata (account/item IDs) against the live GraphQL surface so they can edit any transaction the API exposes, not just the ~30 days the local LevelDB cache happens to hold. Once you've consented to the authenticated network calls writes require, there's no privacy or perf reason to keep reads pinned to the stale cache.
copilot-money-mcp --write --live-reads # equivalent to `--write` alone; --live-reads is redundantConfiguring via Claude Desktop / Cursor
Add the flags to the args array in your MCP config:
{
"mcpServers": {
"copilot-money": {
"command": "copilot-money-mcp",
"args": ["--write"]
}
}
}Restart Claude Desktop / Cursor after editing.
Known Limitations
Local Cache Dependency
This server reads from Copilot Money's local Firestore cache, not the cloud. Firestore's offline persistence caches every document the app has ever fetched, so the local database generally contains all transactions, accounts, budgets, goals, and other data you've viewed in the app. The default Firestore cache size is 100 MB (enough for tens of thousands of transactions), and older documents are only evicted via LRU garbage collection if that limit is exceeded.
To maximize cached data: Open the Copilot Money app and browse through your data (transaction history, accounts, budgets) to ensure it has been fetched and cached locally.
Goals are read-only
get_goals and get_goal_history work (cache-only), but there are no goal write tools — Copilot's GraphQL endpoint doesn't expose goal mutations. Goal creation, editing, and contributions are mobile-only in Copilot itself, and live in a path our project can't reach without iOS / desktop traffic capture.
Investment splits are limited to currently-held securities
get_investment_splits returns split events (date + adjustment multiplier) for securities you currently hold. Securities you no longer hold eventually fall out of the cache. There's no GraphQL endpoint for splits, so this is the only path.
Also: get_investment_prices and get_investment_prices_live already return split- and dividend-adjusted prices (Copilot applies Plaid's adjustment factors server-side). You generally don't need raw split events to back-correct prices.
Live investment prices are ownership-gated
get_investment_prices_live only works for securities currently in your linked accounts. Asking for a price series on a ticker you don't own returns an explicit "not in your linked accounts" error.
Long time-series responses are capped
Time-series live tools (get_balance_history_live, get_networth_live, get_investment_prices_live) cap responses at 500 rows by default to fit the MCP single-tool-result token limit. Pass max_rows / offset to paginate, or narrow time_frame for fewer rows.
get_investment_balance_live has its own, much tighter cap under a different name: history_limit, default 30 points, 0 for the whole series. Its responses always report history_total_count and history_truncated, and its current value is resolved separately so it can never be lost to truncation.
Troubleshooting
Database Not Found
If you see "Database not available":
Ensure Copilot Money is installed and has synced data
Check the database location:
~/Library/Containers/com.copilot.production/Data/Library/Application Support/firestore/__FIRAPP_DEFAULT/copilot-production-22904/mainVerify
.ldbfiles exist in the directoryProvide a custom path:
copilot-money-mcp --db-path /path/to/database
Decode Worker Timed Out
If you see "Decode worker timed out":
Increase the timeout:
copilot-money-mcp --timeout 300000(5 minutes)For 1GB+ databases, also increase Node.js memory:
node --max-old-space-size=4096 dist/cli.js --timeout 300000
No Transactions Found
Open the Copilot Money app and wait for sync
The database structure may have changed — open an issue
Contributing
See CONTRIBUTING.md for development setup, architecture, and how to add new tools.
License
MIT License - See LICENSE for details.
Acknowledgments
Available Tools
14 toolsget_accountsARead-only
Get all accounts with balances, plus summary fields: total_balance (net worth = assets minus liabilities), total_assets, and total_liabilities. Optionally filter by account type (checking, savings, credit, investment). Checks both account_type and subtype fields for better filtering (e.g., finds checking accounts even when account_type is 'depository'). By default, hidden accounts are excluded. name is your Copilot nickname when set, else the provider label — it is user-editable, so key on account_id, never on name. Default rows are terse: account_id, name, account_type, subtype, current_balance, institution_name, iso_currency_code, item_id, plus user_hidden / user_deleted when set (the flags include_hidden controls). That drops the other ~35 document fields. PARTIAL list of what goes, not exhaustive: the embedded holdings array (get_holdings covers it), institution logo images plus their logo_content_type (base64-encoded, several KB each — this PAIR is where the removed include_logos flag went, and the flag gated both, so request them together), mask (the last-4 digits humans identify an account by), available_balance, limit, institution_id, creation_timestamp (when the account was created in Copilot, YYYY-MM-DD — written only on newer rows, so absent means unknown, not old), the denormalized official_name / original_* name dupes, and user_id. Any document field is requestable by name: fields: ["default", "mask", "available_balance"], or "all" / "*" for full rows. include_logos was removed in v3.0.0 — passing it now raises an error naming this migration.
Inputs: fields, account_type, include_hidden.
get_balance_historyARead-only
Get daily balance snapshots for accounts over time. Each entry returns current_balance, available_balance, limit, account_id, and account_name. The response also includes an accounts array listing the distinct account IDs in the paginated page. Requires a granularity parameter (daily, weekly, monthly) to control response size. Weekly and monthly modes downsample by keeping the last data point per period. Filter by account_id and date range.
Inputs: granularity (required), limit, offset, end_date, +2 more.
get_budgetsARead-only
Get budgets from Copilot's native budget tracking. Returns the current-month effective budget per category plus the full amounts map of per-month overrides for history lookups. For parent categories, the returned amount is the resolved total (children + rollovers) that Copilot displays in the Budgets view. Totals use the current-month effective amount.
Inputs: active_only.
get_cache_infoARead-only
Get information about the local data cache, including the date range of cached transactions and total count. Useful for understanding data availability before running historical queries. This tool reads from a local cache that may not contain your complete transaction history. Also reports decode_health: per-collection counts of documents dropped on schema validation failure (a "degraded" status means some cached documents are missing from results).
Inputs: no named parameters.
get_categoriesARead-only
Unified category retrieval tool. Supports multiple views: list (default) - user categories with transaction counts/amounts for a time period; tree - user categories as hierarchical tree; search - search user categories by keyword. Use parent_id to get subcategories. For list view, use period (e.g., "this_month") or start_date/end_date to filter by date. Includes all categories, even those with $0 spent (matching UI behavior).
Inputs: view, query, period, end_date, +2 more.
get_connection_statusARead-only
Get connection status for all linked financial institutions. Shows per-institution sync health including last successful update timestamps for transactions and investments, login requirements, and error states. Use this to check when accounts were last synced or to identify connections needing attention. Also reports decode_health: per-collection counts of cached documents dropped on schema validation failure (a "degraded" status means some documents are missing from results). Also reports scheduled_smoke: the last scheduled API-drift check with timestamp, or null if the weekly job is not installed. Only "fail" means the API drifted; "auth-missing" and "incomplete" mean drift is unknown.
Inputs: no named parameters.
get_goal_historyARead-only
Get monthly progress snapshots for financial goals. Returns current_amount, target_amount, daily data points, and contribution records per month. Filter by goal_id or month range (YYYY-MM). Cache-only: no live-mode (--live-reads) counterpart exists because Copilot's GraphQL endpoint does not expose goal data, so this tool always returns cached LevelDB data regardless of the --live-reads flag.
Inputs: limit, offset, goal_id, end_month, +1 more.
get_goalsARead-only
Get financial goals from Copilot's native goal tracking. Retrieves user-defined savings goals, debt payoff targets, and investment goals. Returns goal details including target amounts, monthly contributions, status (active/paused), start dates, and tracking configuration. Calculates total target amount across all goals. Cache-only: no live-mode (--live-reads) counterpart exists because Copilot's GraphQL endpoint does not expose goal data, so this tool always returns cached LevelDB data regardless of the --live-reads flag.
Inputs: active_only.
get_holdingsARead-only
Get current investment holdings with position-level detail. Returns ticker, name, quantity, current price, equity value, average cost, and total return per holding. Joins data from account holdings, securities, and optionally historical snapshots. Filter by account or ticker symbol. Note: cost_basis may be unavailable for cash-equivalent positions. Positions on hidden and merged accounts are EXCLUDED by default, matching get_accounts — pass include_hidden: true for them. Do NOT sum holdings as portfolio value: unvested stock-plan shares are reported as holdings, so the sum can far exceed the investment balance; with --live-reads use get_investment_balance_live for the total.
Inputs: limit, offset, account_id, ticker_symbol, +2 more.
get_investment_pricesARead-only
Get investment price history for portfolio tracking. Returns one row per (security, period) for stocks, ETFs, mutual funds, and crypto. Filter by ticker symbol, date range, or price type (daily/hf). By default each row is TERSE: the security, the period, and its latest price (latest_price / latest_at) — enough to answer "what is this worth". The full price series (prices, an epoch-millis map) is most of a full row and roughly quadruples response size, so it is omitted unless requested via fields; ask for it only when you need the time series itself, not a current value.
Inputs: limit, fields, offset, end_date, +3 more.
get_investment_splitsARead-only
Get stock split events from the local Firestore cache. Returns one row per (security, effective_date) with the adjustment multiplier (e.g. 0.1 for a 10-for-1 split — multiply pre-split prices/quantities by this value to convert to the post-split equivalent). Joined with the securities collection so each row includes ticker and name. IMPORTANT: prices returned by get_investment_prices and get_investment_prices_live are ALREADY split-adjusted by Copilot. Use this tool only when you need the split events themselves (e.g., for narrative or historical-analysis purposes) — you do NOT need to apply these multipliers to the prices yourself. Securities that have never split are not included in the output. Coverage is limited to securities Copilot currently syncs in your local cache (typically currently-held or recently-held).
Inputs: limit, offset, end_date, start_date, +1 more.
get_recurring_transactionsARead-only
Identify recurring/subscription charges. Combines two data sources: (1) Pattern analysis - finds transactions from same merchant with similar amounts, returns estimated frequency, confidence score, and next expected date. (2) Copilot's native subscription tracking - returns user-confirmed subscriptions stored in the app. Both sources are included by default for comprehensive coverage. Rows in the pattern-analysis recurring array are terse by default: merchant, normalized_merchant, occurrences, average_amount, total_amount, frequency, confidence, category_name, last_date, next_expected_date. That excludes the matched transactions array (already reachable via get_transactions) and confidence_reason (prose explaining the score) — see fields for how to get either back.
Inputs: name, fields, period, end_date, +4 more.
get_transactionsARead-only
Reads from the local LevelDB cache, which may lag behind Copilot's server if the macOS app hasn't synced recently. For real-time data use --live-reads with get_transactions_live. Unified transaction retrieval tool. Supports multiple modes: (1) Filter-based: Use period, date range, category, merchant, amount filters. (2) Single lookup: Provide transaction_id to get one transaction. (3) Text search: Use query for free-text merchant search. (4) Special types: Use transaction_type for foreign, refunds, credits, duplicates, hsa_eligible, tagged. (5) Location-based: Use city or lat/lon with radius_km. (6) Tag filter: Use tag to find transactions with a specific tag. Rows are TERSE by default: transaction_id, date, amount, name, category_name, account_id, item_id, pending, excluded, internal_transfer. excluded answers "is this row excluded from spending?" — the raw per-transaction flag OR the row's category being user-excluded, the same union exclude_excluded filters on — so it is true for a row Copilot never stamped individually. It is therefore nearly always false in a default response, since exclude_excluded already removed those rows; it carries information only when you pass exclude_excluded: false. A cache row carries ~30 fields and most callers need a handful, so the rest are excluded unless asked for. PARTIAL list of what that drops, not exhaustive: Plaid metadata (plaid_category_id, plaid_category_strings, plaid_deleted), internal IDs (category_id, recurring_id, goal_id, parent_transaction_id, children_transaction_ids, user_id), enrichment and intelligence fields (normalized_merchant — still the normalized merchant name when requested — intelligence_suggested_category_ids, suggestion_ids, original_name), tag_ids, review state (user_reviewed, user_note, user_changed_type — true only when a human re-typed the row, so do not second-guess its type), location (city, region, country, lat/lon), and flags like is_amazon/from_investment. amazon is worth naming because nothing else hints it exists: on rows Copilot matched to an Amazon order it carries the receipt — {order_id, items: [{id, name, link, price, quantity}], other: {giftWrapping, rewards, savings, shipping, tax}} — so fields: ["default", "amazon"] answers "what was in this order" without an exported CSV. Ask for any of them by name with fields: ["default", "tag_ids"], or take the whole document with fields: ["all"] (or "*"). category_name is always resolved to a human-readable name. compact was removed in v3.0.0 — passing it now raises an error naming this migration.
Inputs: lat, lon, tag, city, +22 more.
refresh_databaseARead-only
Refresh the in-memory cache by reloading data from the local Copilot Money database. Use this when the user has recently synced new transactions in the Copilot Money app, or when you suspect the cached data is stale. The cache also auto-refreshes every 5 minutes. Returns the updated cache info after refresh.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool targets a distinct resource (transactions, accounts, holdings, budgets, goals, categories, splits, connection/cache status), and the descriptions steer callers correctly for the closest pairs (get_goals vs get_goal_history, get_accounts vs get_balance_history, get_cache_info vs get_connection_status). The main ambiguity comes from get_transactions being a six-mode mega-tool and from multiple tools referencing absent `_live` counterparts (get_transactions_live, get_investment_prices_live, get_investment_balance_live), which an agent cannot call.
All tools use snake_case with a get_<resource> pattern, and the single exception (refresh_database) still follows the verb_noun convention. Resource names are predictable and parallel across domains (get_goals/get_goal_history, get_holdings/get_investment_prices).
14 tools is well within the sweet spot for a personal-finance server covering transactions, accounts, investments, budgets, goals, and cache management. Each tool maps to a real domain object and none look redundant or padding.
Read coverage is thorough across every major domain: accounts, transactions (with search/filter/location/tag modes), balance history, budgets, categories, goals plus goal history, holdings, prices, splits, recurring charges, and cache/connection health. The gap is the absence of any mutation tools (edit transaction category, adjust budget/goal, create tags), so agents can analyze but not change anything.
Maintenance
Related MCP Connectors
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
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.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseBqualityDmaintenanceMCP server that provides AI assistants access to stock market data including financial statements, stock prices, and market news through a Model Context Protocol interface.112,324MIT
- AlicenseAqualityBmaintenanceAn MCP server implementation that provides programmatic access to personal finance data through LunchMoney's API, enabling AI assistants to manage transactions, budgets, categories, and assets.59934 npm115MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Splitwise expenses with atomic duplicate prevention, smart fuzzy matching, and support for flexible split ratios between two people.MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to perform comprehensive Microsoft Excel operations including data analysis, cell editing, advanced formatting, and VBA execution on Windows systems. It provides a structured workflow for managing workbooks and worksheets through a dedicated Model Context Protocol interface.571 npm4MIT