Copilot Money MCP

Copilot Money MCP 服务

使用 AI 查询和管理个人财务数据，数据来自本地 Copilot Money

免责声明

这是一个独立的社区项目，与 Copilot Money 或其母公司没有任何关联，也未获得其认可或支持。 此工具由独立开发者创建，用于通过 AI 查询本地缓存的数据。“Copilot Money”是其各自所有者的商标。

说明

Copilot Money 已宣布推出官方 MCP 服务（目前处于候补名单阶段，且仅支持读取）。 如果官方提供的只读集成符合你的需求，强烈建议你考虑使用它，而不是这个社区项目。访问 agent.copilot.money 了解详情并加入候补名单。

如果你需要写入工具（对交易分类、管理预算、编辑定期项目等）、完全离线且零网络请求的缓存模式读取，或者只是不想等官方推出就立即使用，那么本项目仍然很有用。

警告

官方 MCP Beta 目前不会显示通过 Plaid 连接的账户。 Copilot 团队已确认此限制，并表示正在寻找解决方案，但目前没有时间表。如果你的大多数金融机构都是通过 Plaid 连接的，官方 MCP 展示的财务情况将不完整。本社区服务不受此影响：它会读取应用的完整本地缓存（实时模式下则使用应用所用的同一 GraphQL API），因此包含通过 Plaid 连接的账户。

概述

一个 MCP 服务，可让 AI 助手访问你的 Copilot Money 个人财务数据。它会读取 Mac 上本地缓存的 Firestore 数据库（LevelDB + Protocol Buffers）。所有读取操作都在本地完成，不会发起任何网络请求。

14 个缓存模式读取工具（--live-reads 模式下为 25 个：8 个仍可用的缓存工具 + 17 个实时工具），以及最多 19 个写入工具——用于查询和修改交易、账户、持仓、余额、类别、定期扣费、预算、目标和投资表现。请参阅下文的按模式划分的工具。

贡献者：写入操作会通过一个我们并不拥有的 API 进行。有关仓库如何防止其对 Copilot GraphQL 接口的模型悄然偏离——包括一致性台账、实时冒烟测试和每周偏离检查——请参阅 docs/CONFORMANCE_ARCHITECTURE.md。

隐私优先

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

• 不进行任何形式的分析、遥测或跟踪
• 读取完全在本地进行——零网络请求
• 开源——你可以自行检查代码

重要

关于 AI 提供商的重要提示。 虽然此服务本身在本地运行，绝不会将你的数据发送到本项目运营的任何服务端，但你连接的 AI 助手（Claude、ChatGPT、Gemini 等）会在回答问题时看到你的 Copilot Money 数据。这意味着你的财务数据会传输给并由你选择的模型提供商——Anthropic、OpenAI、Google 或其他第三方——处理，且受该提供商自身的隐私政策和数据保留条款约束。

将此 MCP 服务与托管式 AI 模型搭配使用，即表示你知情并同意与该 AI 提供商共享财务数据。 只有在你能接受这种权衡时才使用此工具。如果无法接受，可以考虑等待 Copilot Money 推出官方集成，或使用完全本地运行的模型。

按模式划分的工具

此服务会根据启用的 CLI 标志提供不同工具。

模式	标志	功能	身份验证	网络	可用工具
🟢 默认	(无)	从本地 LevelDB 缓存读取数据	❌ 无	🔌 零（离线）	14 个缓存模式读取和实用工具
🌐 实时读取	--live-reads	通过 Copilot 的 GraphQL API 实时读取；替换 6 个缓存工具，并添加 11 个仅限实时模式的工具	🔒 浏览器会话	🌐 每次请求使用 HTTPS	25 个读取工具（8 个缓存模式 + 17 个实时模式）
✍️ 写入	--write	添加变更工具（交易、标签、类别、预算、定期交易、拆分），并自动启用 --live-reads——写入需要服务端最新的交易元数据，因此实时读取与写入模式绑定	🔒 浏览器会话	🌐 每次请求使用 HTTPS	在 25 个实时读取工具之外，另加 19 个写入工具

传入 --write 即表示启用 --live-reads；你也可以单独传入 --live-reads，以只读方式实时访问。

📖 完整的逐工具清单、状态、注意事项和已知限制（目标、股票拆分、响应大小上限），请参阅 docs/tools-by-mode.md。

⬆️ 从 v2 升级？ v3.0.0 更改了读取响应的结构——请参阅 docs/MIGRATING-v3.md。没有工具被重命名或移除；行内容变得更简洁，并且有两个参数已弃用。

---

快速开始

前置条件

• Node.js 18+（随 Claude Desktop 捆绑提供）
• Copilot Money（macOS App Store 版本）
• Claude Desktop、Cursor 或任何兼容 MCP 的客户端
• 仅适用于 --live-reads 或 --write： 使用受支持浏览器登录 app.copilot.money——Chromium 系列、Firefox 或 Safari；浏览器列表请参阅 docs/graphql-live-reads.md。 服务会复用该会话的 Firebase 刷新令牌。若未登录，服务仍会启动；首次调用实时读取或写入工具时，会提示助手登录——登录后重试即可，无需重启。默认模式无需任何配置——它会读取本地缓存，且不会发出网络请求。

通过 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 天内所有的 Amazon 购买记录”

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

使用 get_transactions（或通过 --live-reads 使用 get_transactions_live 获取最新数据）和 get_categories（或 get_categories_live），并配合日期范围、文本搜索和类别筛选。

账户概览

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

“显示我的支票账户过去 6 个月的余额，按月统计”

“哪些银行连接需要处理？”

使用 get_accounts（或通过 --live-reads 使用 get_accounts_live 获取最新余额）、get_balance_history（可选使用按账户提供的实时变体 get_balance_history_live）、get_connection_status，以及用于生成净资产随时间变化图表的 get_networth_live。

投资组合

“我目前持有哪些资产，总回报是多少？”

“显示我持有的最大股票过去一年的价格历史”

“我目前的 META 成本基础是多少？”

使用 get_holdings（或使用 get_holdings_live 获取实时成本基础）、get_investment_prices（或使用 get_investment_prices_live 获取证券实时价格历史）。

预算与目标

“我这个月的预算进度如何？”

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

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

使用 get_budgets（或通过 --live-reads 使用 get_budgets_live），以及 get_goals / get_goal_history（仅使用缓存数据——Copilot 的 GraphQL 端点不提供目标数据）。

订阅与定期交易

“我在为哪些订阅付费？”

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

使用 get_recurring_transactions（或通过 --live-reads 使用 get_recurring_live）和 get_upcoming_recurrings_live 获取即将到期但尚未支付的项目。

配置

缓存 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

# Write tools resolve account/item ids for a transaction id via a live
# window fetch when the in-memory index (fed by live reads) misses.
# Default window: 13 months. Raise it to edit older transactions:
COPILOT_WRITE_RESOLVE_WINDOW_MONTHS=30 copilot-money-mcp --write

# Write-resolution routing ids (opaque transaction/account/item ids only —
# never amounts or names) persist whenever live reads are enabled (including
# --write mode), keyed by the logged-in account, so cross-session writes
# skip the live window fetch.
# The same switch also disables the persisted split-parent record
# (split-parents.<uid>.jsonl, opaque ids only): delete_transaction then
# remembers a parent split through this server only until it restarts, and
# after a restart relies on the local cache to refuse it (#842).
# Disable both entirely:
COPILOT_DISABLE_PERSISTENT_INDEX=1 copilot-money-mcp --write

你也可以使用 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

身份验证与可选模式

--live-reads 和 --write 都会向 Copilot Money 的 GraphQL API app.copilot.money/api/graphql 发起经过身份验证的调用。它们需要在 app.copilot.money 上有已登录的浏览器会话——服务会读取 Web 应用存储在浏览器中的同一个 Firebase 刷新令牌。服务会搜索 10 种浏览器：Chrome、Arc、Microsoft Edge、Brave、Vivaldi、Chromium、Opera、Opera GX、Safari 和 Firefox；并会检查每个 Chromium 系列浏览器的所有配置文件，而不只是默认配置文件。有关具体读取哪些文件，以及为何对浏览器范围内的 Local Storage 读取未限定 Copilot 来源的说明，请参阅 PRIVACY.md。

在 Linux 上，服务会改为搜索 Linux 路径：Chrome（~/.config/google-chrome，以及 -beta / -unstable）、Microsoft Edge（~/.config/microsoft-edge）、Brave（~/.config/BraveSoftware/Brave-Browser）、Vivaldi（~/.config/vivaldi）、Chromium（~/.config/chromium 和 snap 版本的 ~/snap/chromium/common/chromium）、Opera（~/.config/opera），以及 Firefox（~/.mozilla/firefox、Firefox 147 及更高版本在没有 ~/.mozilla 时创建新配置文件所用的 ~/.config/mozilla/firefox、snap 版本的 ~/snap/firefox/common/.mozilla/firefox，以及 flatpak 版本的 ~/.var/app/org.mozilla.firefox/.mozilla/firefox）。~/.config 路径遵循 XDG_CONFIG_HOME。Arc、Safari 和 Opera GX 仅支持 macOS。

选择浏览器和配置文件：--browser / --browser-profile

默认情况下，系统会按上述固定顺序尝试浏览器，并使用第一个可用会话。如果机器上登录了多个 Copilot 账户——例如，一个人在 Brave 中登录，另一个人在 Chrome 中登录——请指定要使用的账户：

标志	环境变量	值
--browser <name>	COPILOT_BROWSER	chrome、arc、edge（或 microsoft-edge）、brave、vivaldi、chromium、opera、opera-gx（或 operagx）、safari、firefox——不区分大小写
--browser-profile <name>	COPILOT_BROWSER_PROFILE	Chromium 系列：配置文件目录（Default、Profile 2）或浏览器中显示的配置文件名称。Firefox：配置文件目录（abcd1234.default-release）、第一个点号后的部分（default-release），或 profiles.ini 中的 Name=。不区分大小写。如果名称匹配多个配置文件，将拒绝执行（见下文）。添加前缀 dir: 可仅匹配区分大小写的确切目录名称（dir:Profile 1），添加前缀 name: 可仅匹配显示名称 / Name=（如果名称本身以 dir: 或 name: 开头，则前缀需要重复一次，例如 name:name:Work）。在 Linux 上，Chrome 配置文件名称会在 stable、beta 和 unstable 频道中分别匹配，并搜索所有匹配项。需要指定浏览器。
--browser-data-dir <path>	COPILOT_BROWSER_DATA_DIR	自定义用户数据根目录，用于替换浏览器的默认位置——适用于使用 --user-data-dir 启动的浏览器、便携版安装或复制的配置文件。Chromium 系列：包含 Local State 和 Default / Profile N 目录的文件夹（Opera 还包括其根目录布局的存储）。Firefox：配置文件根目录（包含 profiles.ini 和／或配置文件目录，可直接包含或位于 Profiles/ 下），或单个配置文件目录（包含 storage/default、prefs.js 或 times.json 的目录）。请使用绝对路径：开头的 ~ 会被展开，相对路径则相对于服务的工作目录解析，而 MCP 宿主通常会将该目录设为 /。需要指定浏览器；Safari 不支持。

每个标志的优先级都高于对应的环境变量。选定浏览器后，仅读取该浏览器（如果指定了配置文件，则仅读取该配置文件）——不会回退到其他浏览器，因此会话绝不会在不提示的情况下来自他人的浏览器。如果未找到会话，错误消息会准确指出搜索位置，例如 No Copilot Money session found in Brave (profile "Default"). …，并说明浏览器的数据目录或配置文件是否不存在。 配置文件名称必须恰好选中一个配置文件。显示名称并非唯一，而且 Microsoft Edge 内置配置文件的显示名称与其目录名相差一位（目录 Default 显示为“配置文件 1”，目录 Profile 1 显示为“配置文件 2”），因此，如果某个名称既匹配一个配置文件的目录名，又匹配另一个配置文件的显示名称——或匹配两个显示名称，或匹配两个 Firefox 配置文件——系统会拒绝该名称，且不会搜索任何内容：--browser-profile "Profile 1" is ambiguous in Microsoft Edge: it matches directory "Profile 1" and the display name of directory "Default". Pick exactly one with --browser-profile "dir:Default" or "dir:Profile 1". 拒绝提示中提供的每个值都只会选中一个配置文件：对于 profiles.ini 将其放在配置文件目录外的 Firefox 配置文件，系统会改为提供 name:，因为 dir: 只能匹配列出的目录；如果两个 Firefox 配置文件无法通过名称区分（同一个目录名既直接位于 --browser-data-dir 下，又位于其 Profiles/ 下，或者两个 profiles.ini 条目都带有一个位于配置文件目录外的 Name=），系统会按路径列出它们：移除 --browser-profile 并将 --browser-data-dir 指向所需配置文件即可选中其中一个。dir: 格式始终只会指定一个配置文件，因此在拥有三个或更多配置文件的标准 Edge 中——其中每个中间的 Profile N 既是目录名，又是另一个配置文件的显示名称——所有配置文件仍都可选。目录名与其显示名称相同的目录不会产生歧义。在 Linux 上，如果任何一个 Chrome 渠道内存在歧义，系统会拒绝整个选择，并在消息中指出该渠道的目录。

该选择仅在使用 --live-reads 或 --write 时生效。在这两种模式下，未知浏览器名称、没有浏览器的配置文件、Linux 上仅适用于 macOS 的浏览器，或错误的 --browser-data-dir，都会在服务器启动时导致错误并停止启动。在默认的仅缓存模式下，不会读取任何浏览器，因此无论选择来自标志还是环境变量，也无论选择是否有效，都会被忽略；系统只会在 stderr 输出一行警告，而不会停止服务器。

使用 --browser-data-dir 时，只会读取该目录，不会读取浏览器的默认位置或任何其他浏览器的位置。随后，--browser-profile 会在该目录中匹配配置文件（目录名、Local State 显示名称、Firefox 后缀或 profiles.ini 中的 Name=，其中相对路径的 Path= 条目会基于数据目录解析）。如果该目录指向单个 Firefox 配置文件，则无需使用 --browser-profile；如果指定了其他配置文件，则会被拒绝。如果路径不存在或不是目录、未指定浏览器，或者浏览器为 Safari（其位置由 macOS 固定），服务器将拒绝启动。如果目录中没有会话，错误消息会指出该目录：No Copilot Money session found in Chrome (data dir "/home/me/chrome-profile/Fork-18"). …；如果路径看起来像是单个 Chromium 配置文件（名称为 Default / Profile N，或包含 Preferences 文件），而非其上级的用户数据根目录，错误消息会说明这一点，并建议改用其上级目录并添加 --browser-profile。

{
  "mcpServers": {
    "copilot-money": {
      "command": "copilot-money-mcp",
      "args": ["--live-reads", "--browser", "brave", "--browser-profile", "Default"]
    }
  }
}

或者，也可以在同一条目中使用 "env": { "COPILOT_BROWSER": "brave", "COPILOT_BROWSER_PROFILE": "Default" }。对于使用自定义 --user-data-dir 启动的 Chrome：

"args": ["--live-reads", "--browser", "chrome", "--browser-data-dir", "/home/me/chrome-profile/Fork-18"]

默认模式无需身份验证，也不会发起任何网络请求——读取内容来自本地 LevelDB 缓存。

--live-reads：通过 GraphQL 实时读取

copilot-money-mcp --live-reads

将 6 个缓存模式读取工具（get_transactions、get_accounts、get_categories、get_budgets、get_recurring_transactions、get_holdings）替换为由 GraphQL 支持的实时等效工具，并新增 11 个工具（get_tags_live、get_networth_live、get_upcoming_recurrings_live、get_monthly_spend_live、get_balance_history_live、get_investment_prices_live、refresh_cache、get_investment_allocation_live、get_top_movers_live、get_aggregated_holdings_live、get_investment_balance_live）。

适用于以下情况：

• 你需要 macOS 应用尚未预先获取的交易（自动获取窗口通常约为 30 天；超出此范围后，请打开应用并向前滚动，以强制填充缓存，或使用 --live-reads 直接查询服务）。
• 你需要最新的单只证券成本基础或随时间变化的余额数据。
• macOS 应用最近没有同步。

--write：通过 GraphQL 执行变更（隐含启用 --live-reads）

copilot-money-mcp --write

新增 19 个用于交易、标签、类别、定期交易、预算和拆分交易的变更工具。默认关闭——除非你选择启用，否则服务为只读。

--write 也会自动启用 --live-reads。写入工具会通过实时 GraphQL 接口解析交易元数据（账户／项目 ID），因此可以编辑 API 所提供的任何交易，而不只是本地 LevelDB 缓存中恰好保留的约 30 天数据。在你同意写入所需的经过身份验证的网络调用后，就没有隐私或性能方面的理由继续将读取固定在过时的缓存上。

copilot-money-mcp --write --live-reads   # equivalent to `--write` alone; --live-reads is redundant

通过 Claude Desktop／Cursor 配置

在 MCP 配置的 args 数组中添加这些标志：

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

编辑后，重启 Claude Desktop／Cursor。

已知限制

依赖本地缓存

此服务读取的是 Copilot Money 的本地 Firestore 缓存，而非云端数据。Firestore 的离线持久化会缓存应用曾获取过的每份文档，因此本地数据库通常包含你在应用中查看过的所有交易、账户、预算、目标及其他数据。Firestore 缓存默认大小为 100 MB（足以存储数万笔交易）；只有超出此限制时，才会通过 LRU 垃圾回收机制清除较旧的文档。

**最大限度利用缓存数据：**打开 Copilot Money 应用并浏览你的数据（交易记录、账户、预算），确保这些数据已获取并缓存在本地。

目标为只读

get_goals 和 get_goal_history 可以使用（仅限缓存），但没有用于写入目标的工具——Copilot 的 GraphQL 端点不提供目标变更接口。在 Copilot 中创建、编辑目标和进行目标供款仅限移动端使用，而且这些操作所经由的路径无法由本项目触达，除非捕获 iOS／桌面端流量。

投资拆分仅限当前持有的证券

get_investment_splits 会返回你当前持有的证券的拆分事件（日期 + 调整乘数）。你不再持有的证券最终会从缓存中移除。没有用于查询拆分的 GraphQL 端点，因此这是唯一的途径。

另外：get_investment_prices 和 get_investment_prices_live 已返回经过拆分和股息调整的价格（Copilot 会在服务器端应用 Plaid 的调整系数）。通常无需使用原始拆分事件来回溯修正价格。

实时投资价格受持有情况限制

get_investment_prices_live 仅适用于你关联账户中当前持有的证券。查询你未持有的股票代码的价格序列时，会返回明确的“not in your linked accounts”错误。

长时间序列响应的行数上限

时间序列实时工具（get_balance_history_live、get_networth_live、get_investment_prices_live）默认将响应限制为 500 行，以符合 MCP 单工具结果的令牌上限。传入 max_rows / offset 进行分页，或缩小 time_frame 以减少行数。

get_investment_balance_live 的上限更低，且使用不同的参数名：history_limit，默认值为 30 个数据点，设为 0 可返回整个序列。响应始终会报告 history_total_count 和 history_truncated，并单独解析 current 值，因此它永远不会因截断而丢失。

故障排除

未找到数据库

如果看到“数据库不可用”：

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

解码工作线程超时

如果看到“解码工作线程超时”：

1. 增加超时时间：copilot-money-mcp --timeout 300000（5 分钟）
2. 对于 1GB 以上的数据库，还要增加 Node.js 内存：node --max-old-space-size=4096 dist/cli.js --timeout 300000

未找到交易记录

• 打开 Copilot Money 应用并等待同步
• 数据库结构可能已更改——提交问题

贡献

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

许可证

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

致谢

• 使用 Anthropic 的 MCP SDK 构建
• 使用 Zod 验证数据
• 使用 Bun 开发