copilot-money-mcp

Purpose

copilot-money-mcp is a Model Context Protocol (MCP) server that gives AI assistants access to Copilot Money personal finance data. It reads data from the locally cached Firestore database on Mac (LevelDB + Protocol Buffers). In the default mode, reads are conducted 100% locally with zero network requests. Users can query their transactions, accounts, budgets, investments, and other financial information in natural language through an AI assistant.

This project is an independent, community-driven project, and has no affiliation, endorsement, or connection with Copilot Money or its parent company. Copilot Money has announced an official MCP server (currently in the waitlist phase, read-only). If a first-party read-only integration meets your needs, it is recommended to prioritize using the official version. The value of this community project lies in: providing write tools (categorizing transactions, managing budgets, editing recurring charges, etc.), fully offline cached-mode reads, and being immediately usable without waiting for the official release. In addition, the official MCP beta currently does not display accounts connected via Plaid, whereas this community server reads the app's complete local cache (and in live mode uses the same GraphQL API as the app), so it includes Plaid-connected accounts.

Main Capabilities

Depending on the enabled CLI flags, the server exposes different tool sets:

• Default cache mode: 14 read tools
• --live-reads mode: 8 retained cache tools + 17 live tools, for a total of 25 read tools
• --write mode: adds up to 19 write tools on top of --live-reads (--write implies --live-reads)

What can be queried and modified includes: transactions, accounts, holdings, balances, categories, recurring charges, budgets, goals, and investment performance.

Typical use cases include:

• Spending analysis: query last month's dining expenses, Amazon purchases in the last 30 days, top 5 expense categories of the year (using get_transactions, get_categories, etc., with support for date ranges, text search, and category filters)
• Account overview: query net worth, checking account balance history, bank connection status (using get_accounts, get_balance_history, get_connection_status, get_networth_live, etc.)
• Investment portfolio: query current holdings and total returns, price history of the largest holdings, cost basis of META (using get_holdings, get_investment_prices, etc.)
• Budgets and goals: query budget performance, emergency fund progress, goal history (using get_budgets, get_goals, get_goal_history; goal data is only supported in cache mode)
• Subscriptions and recurring charges: query subscription items and monthly recurring charge amounts (using get_recurring_transactions, get_upcoming_recurrings_live)

Usage

Requirements

• Node.js 18+ (bundled with Claude Desktop)
• Copilot Money (macOS App Store version)
• Claude Desktop, Cursor, or any MCP-compatible client
• Only --live-reads or --write require: a supported browser logged in to app.copilot.money (Chromium-based, Firefox, or Safari). The server reuses that session's Firebase refresh token. If not logged in, the server will still start, and on the first call to a live or write tool it will prompt the assistant to log in; after logging in, just retry, no restart needed. The default mode requires no authentication.

Installing via Claude Desktop

1. Download the latest .mcpb package from Releases
2. Double-click the .mcpb file to install it into Claude Desktop
3. Restart Claude Desktop
4. Start asking financial questions

Installing via npm

Add the configuration to the Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json).

Cursor Installation

1. Install the package globally: npm install -g copilot-money-mcp
2. Open Cursor Settings (Cmd + ,) > Features > MCP Servers
3. Add the server configuration: { "mcpServers": { "copilot-money": { "command": "copilot-money-mcp" } } }

Optional Mode Configuration

Add flags to the args array in the MCP configuration, then restart Claude Desktop / Cursor after editing.

Date Period Parameters

The period parameter supports the following shortcuts: this_month, last_month, last_7_days, last_30_days, last_90_days, ytd, this_year, last_year.

Caching and Performance

The server caches data in memory for 5 minutes, configurable via environment variables. You can also use the refresh_database tool to refresh manually. For large databases (500MB+), you can increase the decode timeout (default 90 seconds); databases over 1GB also require increasing Node.js memory.

Privacy Notice

This project does not collect, store, or transmit user data to any servers of this project (this project has no such servers). There is no analytics, telemetry, or tracking of any kind. In default mode, reads are entirely local. However, note that: the AI assistant connected to the server (Claude, ChatGPT, Gemini, etc.) will see the user's Copilot Money data when answering questions, which means financial data is transmitted to the provider of the chosen model (Anthropic, OpenAI, Google, or another third party), subject to that provider's own privacy policy and data retention terms. You should be aware of this trade-off when using hosted AI models.

Limitations

• Local cache dependency: It reads Copilot Money's local Firestore cache, not the cloud. Firestore offline persistence caches every document the app has fetched, so the local database usually contains all data that has been viewed. The default cache size is 100 MB; only after exceeding that are old documents evicted via LRU garbage collection. To maximize cached data, you can browse transaction history, accounts, budgets, etc. in the Copilot Money app.
• Goals are read-only: get_goals and get_goal_history are available (cache-only mode), but there are no goal write tools—Copilot's GraphQL endpoints do not expose goal mutation operations. Creating, editing, and contributing to goals in Copilot is mobile-only.
• Investment splits are limited to securities in current holdings: get_investment_splits returns split events for currently held securities. Securities no longer held will eventually disappear from the cache, and splits have no GraphQL endpoint. In addition, get_investment_prices and get_investment_prices_live already return prices adjusted for splits and dividends, so raw split events are usually not needed to reverse-adjust prices.
• Live investment prices are limited by holdings: get_investment_prices_live is only valid for securities in currently linked accounts; querying the price series of a ticker you do not hold returns a clear "not in your linked accounts" error.
• Long time-series responses are capped: The time-series live tools by default limit responses to 500 rows to fit MCP's per-tool result token limit. You can paginate with max_rows / offset, or reduce the number of rows by narrowing the time_frame. get_investment_balance_live has a separate, stricter limit history_limit (default 30 points, 0 means the entire series); its response always reports history_total_count and history_truncated, and the current value is parsed separately, so it will not be lost due to truncation.

Troubleshooting

• Database not found: Confirm that 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/main; confirm that .ldb files exist in the directory; a custom path can be provided.
• Decode worker timeout: Increase the timeout; for 1GB+ databases, also increase Node.js memory.
• No transactions found: Open Copilot Money The app is waiting for synchronization; the database schema may have changed, and you can submit an issue.

Technical Notes

Built on Anthropic's MCP SDK, using Zod for data validation and Bun for development. Licensed under MIT. The project also maintains a conformance ledger, live smoke tests, and weekly drift checks to keep the Copilot GraphQL interface model up to date; see docs/CONFORMANCE_ARCHITECTURE.md for details.