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.

[!NOTE] Copilot Money has announced an official MCP server (currently in waitlist, read-only). If a first-party, read-only integration suits your needs, you should strongly consider using it instead of this community project. Learn more and join the waitlist at agent.copilot.money.

This project remains useful if you need write tools (categorize transactions, manage budgets, edit recurrings, etc.), fully offline cache-mode reads with zero network requests, or simply want access today without waiting for the official rollout.

[!WARNING] The official MCP beta currently does not surface Plaid-connected accounts. Copilot's team has confirmed the limitation and says they're working on a path forward, but there's no timeline. If most of your institutions connect through Plaid, the official MCP will give you an incomplete picture of your finances. This community server is not affected: it reads the app's full local cache (and, in live mode, the same GraphQL API the app uses), so Plaid-connected accounts are included.

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

[!IMPORTANT] 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 waiting for an official Copilot Money integration or using a fully local model.

Tools by Mode

This server exposes different tools depending on which CLI flags you enable.

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).

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

Installation via Claude Desktop

1. Download the latest .mcpb bundle from Releases
2. Double-click the .mcpb file to install in Claude Desktop
3. Restart Claude Desktop
4. Start asking questions about your finances!

Installation via npm

npm install -g copilot-money-mcp

Then add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "copilot-money": {
      "command": "copilot-money-mcp"
    }
  }
}

Installation for Cursor

1. Install the package globally:

   Terminal

   Copy

   npm install -g copilot-money-mcp
   

2. Open Cursor Settings (Cmd + ,) > Features > MCP Servers

3. Add the server configuration:

   config.json

   Copy

   {
     "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.
# Disable entirely:
COPILOT_DISABLE_PERSISTENT_INDEX=1 copilot-money-mcp --write

You 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 600000