用途

copilot-money-mcp 是一个模型上下文协议（MCP）服务器，为 AI 助手提供访问 Copilot Money 个人财务数据的能力。它从 Mac 上本地缓存的 Firestore 数据库（LevelDB + Protocol Buffers）读取数据，默认模式下读取 100% 本地进行，零网络请求。用户可以通过 AI 助手以自然语言查询自己的交易、账户、预算、投资等财务信息。

该项目为独立、社区驱动的项目，与 Copilot Money 及其母公司无任何关联、背书或联系。Copilot Money 已宣布官方 MCP 服务器（当前处于等待名单阶段，只读），若第一方只读集成满足需求，建议优先考虑使用官方版本。本社区项目的价值在于：提供写入工具（分类交易、管理预算、编辑定期扣费等）、完全离线的缓存模式读取、以及无需等待官方推出即可立即使用。此外，官方 MCP 测试版目前不显示通过 Plaid 连接的账户，而本社区服务器读取应用完整的本地缓存（实时模式下使用与应用相同的 GraphQL API），因此包含 Plaid 连接的账户。

主要能力

根据启用的 CLI 标志，服务器暴露不同的工具集：

默认缓存模式：14 个读取工具
--live-reads 模式：8 个保留的缓存工具 + 17 个实时工具，共 25 个读取工具
--write 模式：在 --live-reads 基础上增加最多 19 个写入工具（--write 隐含 --live-reads）

可查询和修改的内容包括：交易、账户、持仓、余额、分类、定期扣费、预算、目标以及投资表现。

典型使用场景包括：

支出分析：查询上月餐饮支出、近 30 天 Amazon 购物、年度前 5 大支出类别（使用 get_transactions、get_categories 等，支持日期范围、文本搜索、分类过滤）
账户概览：查询净资产、支票账户余额历史、银行连接状态（使用 get_accounts、get_balance_history、get_connection_status、get_networth_live 等）
投资组合：查询当前持仓与总回报、最大持仓的价格历史、META 的成本基础（使用 get_holdings、get_investment_prices 等）
预算与目标：查询预算执行情况、应急基金进度、目标历史（使用 get_budgets、get_goals、get_goal_history，目标数据仅缓存模式支持）
订阅与定期扣费：查询订阅项目、每月定期扣费金额（使用 get_recurring_transactions、get_upcoming_recurrings_live）

使用方式

环境要求

Node.js 18+（Claude Desktop 自带）
Copilot Money（macOS App Store 版本）
Claude Desktop、Cursor 或任何兼容 MCP 的客户端
仅 --live-reads 或 --write 需要：已登录 app.copilot.money 的受支持浏览器（Chromium 系列、Firefox 或 Safari）。服务器复用该会话的 Firebase 刷新令牌。若没有登录，服务器仍会启动，首次调用实时或写入工具时会提示助手登录，登录后重试即可，无需重启。默认模式无需任何认证。

通过 Claude Desktop 安装

从 Releases 下载最新的 .mcpb 包
双击 .mcpb 文件安装到 Claude Desktop
重启 Claude Desktop
开始询问财务问题

通过 npm 安装

添加配置到 Claude Desktop 配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）。

Cursor 安装

全局安装包：npm install -g copilot-money-mcp
打开 Cursor 设置（Cmd + ,）> Features > MCP Servers
添加服务器配置：{ "mcpServers": { "copilot-money": { "command": "copilot-money-mcp" } } }

可选模式配置

在 MCP 配置的 args 数组中添加标志，编辑后重启 Claude Desktop / Cursor。

日期周期参数

period 参数支持以下快捷方式：this_month、last_month、last_7_days、last_30_days、last_90_days、ytd、this_year、last_year。

缓存与性能

服务器在内存中缓存数据 5 分钟，可通过环境变量配置。也可使用 refresh_database 工具手动刷新。对于大型数据库（500MB+），可增加解码超时（默认 90 秒）；超过 1GB 的数据库还需增加 Node.js 内存。

隐私说明

本项目不收集、存储或传输用户数据到本项目的任何服务器（本项目没有此类服务器）。无分析、遥测或任何形式的追踪。默认模式读取完全本地。但需注意：连接服务器的 AI 助手（Claude、ChatGPT、Gemini 等）在回答问题时将看到用户的 Copilot Money 数据，这意味着财务数据会传输给所选模型的提供商（Anthropic、OpenAI、Google 或其他第三方），受该提供商自身的隐私政策与数据保留条款约束。使用托管 AI 模型时应知晓这一权衡。

限制

本地缓存依赖：读取的是 Copilot Money 的本地 Firestore 缓存，而非云端。Firestore 离线持久化会缓存应用获取过的每个文档，因此本地数据库通常包含所有已查看过的数据。默认缓存大小为 100 MB，超出后才通过 LRU 垃圾回收淘汰旧文档。为最大化缓存数据，可在 Copilot Money 应用中浏览交易历史、账户、预算等。
目标只读：get_goals 和 get_goal_history 可用（仅缓存模式），但没有目标写入工具——Copilot 的 GraphQL 端点不暴露目标变更操作。目标的创建、编辑和缴款在 Copilot 中仅限移动端。
投资拆股仅限于当前持仓的证券：get_investment_splits 返回当前持有证券的拆股事件。不再持有的证券最终会从缓存中消失，且拆股无 GraphQL 端点。另外 get_investment_prices 和 get_investment_prices_live 已返回拆股和股息调整后的价格，通常无需原始拆股事件来反校正价格。
实时投资价格受持仓限制：get_investment_prices_live 仅对当前关联账户中的证券有效，查询未持有股票代码的价格序列会返回明确的“不在您关联账户中”错误。
长时间序列响应有上限：时间序列实时工具默认将响应限制为 500 行，以适应 MCP 单工具结果的 token 限制。可通过 max_rows / offset 分页，或缩小 time_frame 减少行数。get_investment_balance_live 有单独的、更严格的限制 history_limit（默认 30 个点，0 表示整个序列）；其响应始终报告 history_total_count 和 history_truncated，当前值单独解析，不会因截断而丢失。

故障排除

数据库未找到：确认 Copilot Money 已安装并同步了数据；检查数据库位置 ~/Library/Containers/com.copilot.production/Data/Library/Application Support/firestore/__FIRAPP_DEFAULT/copilot-production-22904/main；确认目录中存在 .ldb 文件；可提供自定义路径。
解码工作线程超时：增加超时时间；对于 1GB+ 数据库同时增加 Node.js 内存。
未找到交易：打开 Copilot Money 应用等待同步；数据库结构可能已变更，可提交 issue。

技术说明

基于 Anthropic 的 MCP SDK 构建，使用 Zod 进行数据验证，使用 Bun 开发。采用 MIT 许可证。项目还维护了一个一致性台账（conformance ledger）、实时冒烟测试和每周漂移检查，以保持对 Copilot GraphQL 接口模型的更新，详见 docs/CONFORMANCE_ARCHITECTURE.md。

copilot-money-mcp

工具介绍

用途