Copilot Money MCP 服务器

使用本地 Copilot Money 数据，通过 AI 查询和管理您的个人财务

免责声明

这是一个独立的、社区驱动的项目，与 Copilot Money 或其母公司没有任何关联、认可或联系。 此工具由独立开发者创建，旨在实现对本地缓存数据的 AI 驱动查询。“Copilot Money”是其各自所有者的商标。

概述

一个 MCP 服务器，允许 AI 助手访问您的 Copilot Money 个人财务数据。它从您 Mac 上本地缓存的 Firestore 数据库（LevelDB + Protocol Buffers）中读取数据。读取操作 100% 本地化，零网络请求。 可选的写入模式（通过 --write 启用）会将您请求的更改直接发送到 Copilot Money 的 Firebase/Firestore 后端——即 Copilot Money 应用本身使用的后端——并使用您自己的凭据进行身份验证，绝不通过任何第三方服务。

35 个工具，涵盖支出、投资、预算、目标等：

• 17 个读取工具 — 查询交易、账户、持仓、余额、类别、定期扣款、预算、目标、投资表现等

• 18 个写入工具（可选） — 合并交易更改、管理标签、创建预算、更新定期项目并整理您的财务

默认只读。 写入工具需要显式地以 --write 参数启动服务器才能启用。

隐私至上

我们从不收集、存储或将您的数据传输到本项目运营的任何服务器——我们没有任何服务器。详情请参阅我们的 隐私政策。

• 无任何形式的分析、遥测或跟踪

• 读取完全本地化 — 零网络请求

• 默认只读（除非您传入 --write，否则禁用写入工具）

• 在可选的写入模式下，请求直接从您的机器发送到 Copilot Money 自己的 Firebase/Firestore 后端，使用您自己的凭据 — 绝不通过任何第三方服务

• 开源 — 您可以自行验证代码

快速入门

先决条件

• Node.js 18+（随 Claude Desktop 捆绑提供）

• Copilot Money（macOS App Store 版本）

• Claude Desktop、Cursor 或任何兼容 MCP 的客户端

通过 Claude Desktop 安装

1. 从 Releases 下载最新的 .mcpb 捆绑包

2. 双击 .mcpb 文件以安装到 Claude Desktop

3. 重启 Claude Desktop

4. 开始询问有关您财务的问题！

通过 npm 安装

npm install -g copilot-money-mcp

然后添加到您的 Claude Desktop 配置中 (~/Library/Application Support/Claude/claude_desktop_config.json)：

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

为 Cursor 安装

1. 全局安装该包：

npm install -g copilot-money-mcp

2. 打开 Cursor 设置 (Cmd + ,) > Features > MCP Servers

3. 添加服务器配置：

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

您可以做什么

支出分析

“我上个月在外出就餐上花了多少钱？”

“显示我过去 30 天内所有的亚马逊购物记录”

“今年我支出最高的前 5 个类别是什么？”

使用 get_transactions、get_categories 配合日期范围、文本搜索和类别过滤器。

账户概览

“我所有账户的总净资产是多少？”

“显示我过去 6 个月支票账户的每月余额”

“哪些银行连接需要注意？”

使用 get_accounts、get_balance_history、get_connection_status。

投资组合

“我目前的持仓和总回报是多少？”

“显示 AAPL 过去一年的价格历史”

“本季度我的时间加权回报率是多少？”

使用 get_holdings、get_investment_prices、get_securities、get_investment_performance、get_twr_returns。

预算与目标

“我这个月的预算执行情况如何？”

“我的应急基金进展如何？”

“显示我过去 6 个月的目标历史”

使用 get_budgets、get_goals、get_goal_history。

订阅与定期扣款

“我正在支付哪些订阅费用？”

“我每月在定期扣款上花费多少钱？”

使用 get_recurring_transactions。

整理您的财务（写入模式）

“将我所有的 Uber 交易归类为交通”

“用 #vacation 标记我的度假支出”

“创建一个 500 美元的每月餐饮预算”

“将 Netflix 设置为每月定期扣款”

使用 update_transaction、create_budget、update_recurring 等写入工具。需要 --write 标志。

可用工具

读取工具 (17)

写入工具 (18) — 需要 --write 标志

写入模式

默认情况下，服务器以 只读模式 启动。要启用写入工具，请使用 --write 标志启动服务器：

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

写入工具通过直接向 Copilot Money 的 Firebase/Firestore 后端（即 Copilot Money 应用使用的后端）发送经过身份验证的请求来修改您的 Copilot Money 数据，因此您的更改会立即反映在您的账户中。写入操作使用从您的本地 Copilot Money 会话中提取的 Firebase 刷新令牌进行身份验证；您的凭据绝不会离开您的机器，除非是在向 Google 的 Firebase/Firestore 端点发出的经过身份验证的请求中。不涉及任何第三方服务。详情请参阅 PRIVACY.md。

配置

缓存 TTL

服务器在内存中缓存数据 5 分钟。通过环境变量进行配置：

# 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

您也可以使用 refresh_database 工具手动刷新。

解码超时

对于大型数据库（500MB+），请增加解码超时时间（默认：90 秒）：

# Via environment variable
DECODE_TIMEOUT_MS=600000 copilot-money-mcp

# Via CLI flag
copilot-money-mcp --timeout 600000

对于超过 1GB 的数据库，还需增加 Node.js 内存：

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

支持的日期周期

period 参数支持以下快捷方式：

this_month last_month last_7_days last_30_days last_90_days ytd this_year last_year

已知限制

本地缓存依赖

此服务器从 Copilot Money 的 本地 Firestore 缓存 读取数据，而不是从云端。Firestore 的离线持久化会缓存应用获取过的每一个文档，因此本地数据库通常包含您在应用中查看过的所有交易、账户、预算、目标和其他数据。默认的 Firestore 缓存大小为 100 MB（足以容纳数万条交易），只有在超过该限制时，旧文档才会通过 LRU 垃圾回收机制被清除。

最大化缓存数据： 打开 Copilot Money 应用并浏览您的数据（交易历史、账户、预算），以确保它们已被获取并缓存在本地。

故障排除

找不到数据库

如果您看到“Database not available”：

1. 确保已安装 Copilot Money 并已同步数据

2. 检查数据库位置：~/Library/Containers/com.copilot.production/Data/Library/Application Support/firestore/__FIRAPP_DEFAULT/copilot-production-22904/main

3. 验证目录中是否存在 .ldb 文件

4. 提供自定义路径：copilot-money-mcp --db-path /path/to/database

解码工作进程超时

如果您看到“Decode worker timed out”：

1. 增加超时时间：copilot-money-mcp --timeout 300000（5 分钟）

2. 对于 1GB+ 的数据库，还需增加 Node.js 内存：node --max-old-space-size=4096 dist/cli.js --timeout 300000

未找到交易记录

• 打开 Copilot Money 应用并等待同步

• 数据库结构可能已更改 — 提交 issue

贡献

请参阅 CONTRIBUTING.md 了解开发设置、架构以及如何添加新工具。

许可证

MIT 许可证 - 详情请参阅 LICENSE。

致谢

• 使用 Anthropic 的 MCP SDK 构建

• 使用 Zod 进行数据验证

• 使用 Bun 开发