Copilot Money MCP Server

What is Copilot Money MCP Server about?

Provides an MCP server that exposes 35 AI‑driven tools for reading and optionally writing personal finance information stored in the locally cached Copilot Money Firestore database. All reads are performed completely offline; writes (when enabled with --write) are sent securely to Copilot Money’s own Firebase/Firestore backend using the user’s credentials.

How to use Copilot Money MCP Server?

Install the CLI globally (or via npx) npm install -g copilot-money-mcp.
Add a server entry to your MCP‑compatible client (Claude Desktop, Cursor, etc.) pointing to the copilot-money-mcp command. Example for Claude Desktop:
```
{
  "mcpServers": {
    "copilot-money": {
      "command": "copilot-money-mcp"
    }
  }
}
```
Start the server (read‑only). To enable write tools, launch with the --write flag.
Ask natural‑language finance questions; the server routes them to the appropriate tool and returns structured results.

Key Features

17 read tools (transactions, accounts, budgets, goals, investments, recurring charges, cache info, etc.).
18 write tools (update/create/delete transactions, tags, categories, budgets, goals, recurring items) – gated behind --write.
Zero network traffic for reads – data stays on the local machine.
Optional write mode sends authenticated requests directly to Copilot Money’s backend; no third‑party services involved.
Configurable cache TTL via COPILOT_CACHE_TTL_MINUTES.
Adjustable decode timeout and Node memory limits for large databases.
Built with Bun, TypeScript, LevelDB, Protocol Buffers, and Zod for validation.

Use Cases

Quickly ask “How much did I spend on dining out last month?” and receive an exact total.
Generate a net‑worth overview across all accounts.
Retrieve investment performance metrics such as time‑weighted returns.
Review subscription spending and identify recurring charges.
In write mode, bulk‑categorize or tag transactions, create new budgets, or set up recurring payments directly from natural language commands.

FAQ

Q: Do any of my financial data leave my computer? A: Reads are fully local. Writes are sent only to Copilot Money’s own Firebase/Firestore endpoints using your credentials; no other third‑party servers are involved.

Q: What AI model will see my data? A: The MCP server itself does not send data anywhere, but the AI assistant you connect (Claude, ChatGPT, Gemini, etc.) will receive the data as part of the conversation.

Q: How can I enable write capabilities? A: Start the server with the --write flag, e.g., copilot-money-mcp --write. The client configuration can also include the flag in the args array.

Q: My database is large and the server times out. A: Increase the timeout with --timeout <ms> or the DECODE_TIMEOUT_MS env variable, and raise Node’s memory limit using --max-old-space-size.

Q: Where is the local Firestore cache located? A: ~/Library/Containers/com.copilot.production/Data/Library/Application Support/firestore/__FIRAPP_DEFAULT/copilot-production-22904/main – you can override with --db-path.

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.

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. Optional write mode (opt-in via --write) sends your requested changes directly to Copilot Money's Firebase/Firestore backend — the same backend the Copilot Money app itself uses — authenticated with your own credentials, never through any third-party service.

35 tools across spending, investments, budgets, goals, and more:

17 read tools — query transactions, accounts, holdings, balances, categories, recurring charges, budgets, goals, investment performance, and more
18 write tools (opt-in) — consolidate transaction changes, manage tags, create budgets, update recurring items, and organize your finances

Read-only by default. Write tools require explicitly starting the server with --write to enable.

Demo

Organizing transactions with natural language — categorize, tag, and clean up your feed in one pass:

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
Read-only by default (write tools disabled unless you pass --write)
In opt-in write mode, requests go directly from your machine to Copilot Money's own Firebase/Firestore backend using your own credentials — never through any third-party service
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.

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

Download the latest .mcpb bundle from Releases
Double-click the .mcpb file to install in Claude Desktop
Restart Claude Desktop
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

Install the package globally:
```
npm install -g copilot-money-mcp
```
Open Cursor Settings (Cmd + ,) > Features > MCP Servers

Add 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, get_categories 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, get_balance_history, get_connection_status.

Investment Portfolio

"What are my current holdings and total returns?"

"Show me AAPL price history for the past year"

"What's my time-weighted return this quarter?"

Uses get_holdings, get_investment_prices, get_securities, get_investment_performance, get_twr_returns.

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, get_goals, get_goal_history.

Subscriptions & Recurring

"What subscriptions am I paying for?"

"How much do I spend on recurring charges per month?"

Uses get_recurring_transactions.

Organizing Your Finances (Write Mode)

"Categorize all my Uber transactions as transportation"

"Tag my vacation spending with #vacation"

"Create a $500 monthly dining budget"

"Set up Netflix as a monthly recurring charge"

Uses write tools like update_transaction, create_budget, update_recurring, and more. Requires --write flag.

Available Tools

Read Tools (17)

Tool	Description
`get_transactions`	Query transactions with filters — date range, category, merchant, amount, account, location, text search, and special types (foreign, refunds, duplicates, HSA-eligible).
`get_accounts`	List all accounts with balances, filter by type (checking, savings, credit, investment). Includes net worth calculation.
`get_categories`	List categories with transaction counts and spending totals. Supports list, tree, and search views.
`get_recurring_transactions`	Identify subscriptions and recurring charges with frequency, cost, and next expected date.
`get_budgets`	Get budgets with spending vs. limit comparisons.
`get_goals`	Get financial goals with target amounts, progress, and monthly contributions.
`get_goal_history`	Monthly progress snapshots for goals with daily data and contribution records.
`get_balance_history`	Daily balance snapshots for accounts over time. Supports daily, weekly, or monthly granularity.
`get_holdings`	Current investment holdings with ticker, quantity, price, cost basis, and total return.
`get_investment_prices`	Historical price data (daily + high-frequency) for stocks, ETFs, mutual funds, and crypto.
`get_investment_splits`	Stock split history with ratios, dates, and multipliers.
`get_investment_performance`	Per-security investment performance data.
`get_twr_returns`	Time-weighted return (TWR) monthly data for investment holdings.
`get_securities`	Security master data — ticker, name, type, price, and identifiers (ISIN/CUSIP).
`get_connection_status`	Bank sync health for linked institutions, including last sync timestamps and errors.
`get_cache_info`	Local cache metadata — date range, transaction count, cache age.
`refresh_database`	Reload data from disk. Cache auto-refreshes every 5 minutes.

Write Tools (18) — requires `--write` flag

Category	Tools
Transactions	`update_transaction` (multi-field patch), `review_transactions`
Tags	`create_tag`, `update_tag`, `delete_tag`
Categories	`create_category`, `update_category`, `delete_category`
Budgets	`create_budget`, `update_budget`, `delete_budget`
Goals	`create_goal`, `update_goal`, `delete_goal`
Recurring	`create_recurring`, `update_recurring`, `set_recurring_state`, `delete_recurring`

Write Mode

By default, the server starts in read-only mode. To enable write tools, start the server with the --write flag:

{
  "mcpServers": {
    "copilot-money": {
      "command": "copilot-money-mcp",
      "args": ["--write"]
    }
  }
}

Write tools modify your Copilot Money data by sending authenticated requests directly to Copilot Money's Firebase/Firestore backend — the same backend the Copilot Money app uses — so your changes are immediately reflected in your account. Writes authenticate using a Firebase refresh token extracted from your local Copilot Money session; your credentials never leave your machine except in the authenticated request to Google's Firebase/Firestore endpoints. No third-party services are involved. See PRIVACY.md for full details.

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

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

For 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

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.

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/main
Verify .ldb files exist in the directory
Provide 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

Built with MCP SDK by Anthropic
Data validation with Zod
Developed with Bun

Copilot Money MCP Server