Copilot Money MCP Server

AI-powered personal finance queries 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

This MCP (Model Context Protocol) server enables AI-powered queries of your Copilot Money personal finance data by reading locally cached Firestore data (LevelDB + Protocol Buffers). 100% local processing - no network requests, all data stays on your machine.

Key Features:

🔒 100% Local & Private - Reads from local cache, zero network requests
🤖 AI-Powered - Natural language queries via Claude Desktop
⚡ Fast - Processes thousands of transactions in under 2 seconds
🛡️ Read-Only - Never modifies your Copilot Money data
📦 Easy Install - One-click .mcpb bundle for Claude Desktop

Privacy First

Your financial data never leaves your machine. See our Privacy Policy for details.

✅ No data collection or transmission
✅ No external API calls
✅ No analytics or telemetry
✅ Read-only access to local database
✅ Open source - verify the code yourself

Quick Start

Prerequisites

Node.js 18+ (comes bundled with Claude Desktop)
Copilot Money (macOS App Store version)
Claude Desktop with MCP support

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 + ,)
Search for "MCP" or go to Features > MCP Servers

Add the server configuration:

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

Done

Manual Installation for Development

# Clone the repository
git clone https://github.com/ignaciohermosillacornejo/copilot-money-mcp.git
cd copilot-money-mcp

# Install dependencies
bun install

# Build the project
bun run build

# Run tests
bun test

First-Time Setup

After installing the MCP server, Claude Desktop will request one-time approval for each tool when you first use them. This is a standard security feature for all MCP servers.

What to expect:

You'll see approval prompts as you use different tools
Each prompt shows the tool name and what it does
After approving once, the tools work seamlessly without further prompts

Why this happens:

Claude Desktop requires explicit user consent before an MCP tool can access your data
Even though all our tools are read-only (with readOnlyHint: true), Claude Desktop shows these prompts as a security best practice
This is normal behavior and not specific to this MCP server

After first use: Once you've approved all tools, they'll work instantly without any prompts in future conversations!

Working Examples

Example 1: Monthly Spending Analysis

User Query:

"How much did I spend on dining out last month?"

MCP Tool Call:

{
  "tool": "get_transactions",
  "arguments": {
    "category": "food_and_drink",
    "period": "last_month"
  }
}

Claude's Answer:

"Last month you spent $487.50 on dining out across 23 transactions. Your largest expense was $67.50 at The Italian Place on January 15th."

Example 2: Finding Specific Transactions

User Query:

"Show me all my Amazon purchases in the last 30 days"

MCP Tool Call:

{
  "tool": "get_transactions",
  "arguments": {
    "merchant": "amazon",
    "period": "last_30_days"
  }
}

Claude's Answer:

"You made 7 Amazon purchases in the last 30 days, totaling $234.87. The largest was $47.99 on January 5th. You also had a Prime subscription charge of $23.50."

Example 3: Account Overview

User Query:

"What's my current account balance across all accounts?"

MCP Tool Call:

{
  "tool": "get_accounts",
  "arguments": {}
}

Claude's Answer:

"Your total balance across all accounts is $12,547.83. This includes:

Chase Checking: $3,247.50

Ally Savings: $8,500.33

Chase Freedom Credit: $800.00 (current balance)"

Available Tools

The MCP server provides 8 read-only tools for querying your financial data:

Tool	Description
`get_transactions`	Query transactions with filters (date, category, merchant, amount, account, location). Supports period shortcuts, text search, and special types (foreign, refunds, duplicates).
`get_accounts`	List all accounts with balances, optionally filter by type (checking, savings, credit, investment).
`get_categories`	List all transaction categories with human-readable names, transaction counts, and spending totals. Filter by date range.
`get_recurring_transactions`	Identify subscriptions and recurring charges with frequency, monthly cost, and next expected date. Filter by name for detailed view.
`get_budgets`	Get budgets from Copilot's native budget tracking with spending vs. limit comparisons.
`get_goals`	Get financial goals with progress tracking, monthly history, and savings status.
`get_cache_info`	Get information about the local data cache, including date range and transaction count.
`refresh_database`	Refresh the in-memory cache to pick up newly synced data from Copilot Money. Cache auto-refreshes every 5 minutes.

See tool schemas in Claude Desktop or use the MCP Inspector for complete parameter documentation.

Development

Build Commands

# Install dependencies
bun install

# Run tests
bun test

# Build for production
bun run build

# Build .mcpb bundle
bun run pack:mcpb

# Type checking
bun run typecheck

# Linting
bun run lint
bun run lint:fix

# Formatting
bun run format
bun run format:check

# Run all checks (typecheck + lint + format + test)
bun run check

Project Structure

copilot-money-mcp/
├── src/
│   ├── core/              # Database abstraction & binary decoder
│   ├── models/            # Zod schemas (Transaction, Account, Category)
│   ├── tools/             # MCP tool implementations
│   ├── utils/             # Date utilities
│   ├── server.ts          # MCP server
│   └── cli.ts             # CLI entry point
├── tests/
│   ├── core/              # Core module tests
│   └── tools/             # Tool tests
├── dist/                  # Compiled output
├── PRIVACY.md             # Privacy policy
└── manifest.json          # .mcpb metadata

Architecture

Data Flow:

Copilot Money stores data in local LevelDB/Firestore cache
Binary decoder reads .ldb files and parses Protocol Buffers
Database layer provides filtered access to transactions/accounts
MCP tools expose functionality via Model Context Protocol
Claude Desktop sends queries → MCP server responds

Technical Stack:

Runtime: Node.js 18+ (ESM modules)
Language: TypeScript 5.3+
Validation: Zod schemas
Database: LevelDB (classic-level) + Protocol Buffers
Testing: Bun test runner (772 tests, 100% passing)
MCP SDK: @modelcontextprotocol/sdk v1.2

Testing

# Run all tests
bun test

# Watch mode
bun test --watch

# Run specific test file
bun test tests/tools/tools.test.ts

Test Coverage:

✅ 772 tests passing
✅ 1920+ assertions
✅ Core decoder tests
✅ Database abstraction tests
✅ Tool implementation tests
✅ Schema validation tests
✅ Integration tests

Data Privacy & Security

Read our full Privacy Policy

Key commitments:

No Data Transmission: Zero network requests, all processing local
Read-Only Access: Never modifies your Copilot Money database
No Telemetry: No analytics, crash reports, or tracking
Open Source: Verify privacy claims by reviewing the code
macOS Sandbox: Respects macOS file system permissions

Supported Date Periods

The period parameter supports these shortcuts:

this_month - Current month (Jan 1 - today if in January)
last_month - Previous calendar month
last_7_days - Rolling 7-day window
last_30_days - Rolling 30-day window
last_90_days - Rolling 90-day window
ytd - Year-to-date (Jan 1 - today)
this_year - Current calendar year
last_year - Previous calendar year

Configuration

Cache TTL

The MCP server caches data in memory for 5 minutes by default. You can configure this 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 manually refresh the cache using the refresh_database tool.

Decode Timeout

For large databases (500MB+), you may need to increase the decode timeout. The default is 90 seconds (90,000ms).

Via environment variable:

DECODE_TIMEOUT_MS=600000 copilot-money-mcp

Via CLI flag:

copilot-money-mcp --timeout 600000

In Claude Desktop config (with increased Node.js memory for 1GB+ databases):

{
  "mcpServers": {
    "copilot-money": {
      "command": "node",
      "args": [
        "--max-old-space-size=4096",
        "/path/to/copilot-money-mcp/dist/cli.js",
        "--db-path",
        "/path/to/your/database",
        "--timeout",
        "600000"
      ]
    }
  }
}

Known Limitations

Local Cache Size

This MCP server reads from Copilot Money's local Firestore cache, not directly from the cloud. The cache typically contains:

~500 recent transactions (not your full history)
Accounts, budgets, goals, and recurring transactions
Data synced during recent app usage

Why this limitation exists: Copilot Money uses Firebase/Firestore with App Check security, which prevents direct cloud database access. The local cache is an offline copy maintained by the app for performance.

To maximize cached data:

Open the Copilot Money app regularly
Scroll through your transaction history to trigger sync
The cache updates when you interact with the app

What you get: While you may have thousands of transactions in Copilot Money, only recently accessed/synced data is available locally. This is sufficient for most queries (recent spending, current budgets, recurring charges) but won't include your complete historical data.

Troubleshooting

Database Not Found

If you see "Database not available":

Ensure Copilot Money is installed and has synced data
Check 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 custom path: copilot-money-mcp --db-path /path/to/database

Decode Worker Timed Out (Large Databases)

If you see "Decode worker timed out after Xms":

Your database may be too large for the default 90-second timeout
Increase the timeout: copilot-money-mcp --timeout 300000 (5 minutes)
For databases over 1GB, also increase Node.js memory: node --max-old-space-size=4096 dist/cli.js --timeout 300000
Set via environment variable: DECODE_TIMEOUT_MS=600000

No Transactions Found

Copilot Money may not have synced yet - open the app and wait for sync
The database structure may have changed - open an issue with details

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT License - See LICENSE for details.

Acknowledgments

Built with MCP SDK by Anthropic
Reverse engineering findings documented in REVERSE_ENGINEERING_FINDING.md
Data validation with Zod
Developed with Bun for fast TypeScript development

References

⭐ Star this repo if you find it useful!

Copilot Money MCP Server

Disclaimer

Overview

Privacy First

Quick Start

Prerequisites

Installation via Claude Desktop

Installation via npm

Installation for Cursor

Manual Installation for Development

First-Time Setup

Working Examples

Example 1: Monthly Spending Analysis

Example 2: Finding Specific Transactions

Example 3: Account Overview

Available Tools

Development

Build Commands

Project Structure

Architecture

Testing

Data Privacy & Security

Supported Date Periods

Configuration

Cache TTL

Decode Timeout

Known Limitations

Local Cache Size

Troubleshooting

Database Not Found

Decode Worker Timed Out (Large Databases)

No Transactions Found

Contributing

License

Acknowledgments

References

Yorumlar (0)