MCP server for Copilot Money - AI-powered personal finance queries using local data
npm install copilot-money-mcp> AI-powered personal finance queries using local Copilot Money data




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.
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
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
- Node.js 18+ (comes bundled with Claude Desktop)
- Copilot Money (macOS App Store version)
- Claude Desktop with MCP support
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!
``bash`
npm install -g copilot-money-mcp
Then add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):
`json`
{
"mcpServers": {
"copilot-money": {
"command": "copilot-money-mcp"
}
}
}
`bashClone the repository
git clone https://github.com/ignaciohermosillacornejo/copilot-money-mcp.git
cd copilot-money-mcp
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 serverAfter first use: Once you've approved all tools, they'll work instantly without any prompts in future conversations!
Working Examples
$3
User Query:
> "How much did I spend on dining out last month?"
MCP Tool Call:
`json
{
"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."
---
$3
User Query:
> "Show me all my Amazon purchases in the last 30 days"
MCP Tool Call:
`json
{
"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."
---
$3
User Query:
> "What's my current account balance across all accounts?"
MCP Tool Call:
`json
{
"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
$3
`bash
Install dependencies
bun installRun tests
bun testBuild for production
bun run buildBuild .mcpb bundle
bun run pack:mcpbType checking
bun run typecheckLinting
bun run lint
bun run lint:fixFormatting
bun run format
bun run format:checkRun all checks (typecheck + lint + format + test)
bun run check
`$3
`
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
`$3
Data Flow:
1. Copilot Money stores data in local LevelDB/Firestore cache
2. Binary decoder reads
.ldb files and parses Protocol Buffers
3. Database layer provides filtered access to transactions/accounts
4. MCP tools expose functionality via Model Context Protocol
5. Claude Desktop sends queries ā MCP server respondsTechnical 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
`bash
Run all tests
bun testWatch mode
bun test --watchRun 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 yearConfiguration
$3
The MCP server caches data in memory for 5 minutes by default. You can configure this via environment variable:
`bash
Set cache TTL to 10 minutes
COPILOT_CACHE_TTL_MINUTES=10 copilot-money-mcpDisable 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.Known Limitations
$3
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:
1. Open the Copilot Money app regularly
2. Scroll through your transaction history to trigger sync
3. 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
$3
If you see "Database not available":
1. Ensure Copilot Money is installed and has synced data
2. Check database location:
~/Library/Containers/com.copilot.production/Data/Library/Application Support/firestore/__FIRAPP_DEFAULT/copilot-production-22904/main
3. Verify .ldb files exist in the directory
4. Provide custom path: copilot-money-mcp --db-path /path/to/database$3
- 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:
1. Fork the repository
2. Create a feature branch (
git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature`)MIT License - See LICENSE for details.
- 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
- Model Context Protocol
- Copilot Money
- Privacy Policy
- Reverse Engineering Findings
---
ā Star this repo if you find it useful!