ZenMoney

mcp-server-zenmoney

适用于 ZenMoney（Дзен-мани）的 MCP 服务。它让 AI Agent 能够访问你的账户和余额、搜索交易并生成报告、读取和设置月度预算、查看计划中的（定期）操作和债务、为支出分类，以及在安全机制的保障下记录或编辑交易。它使用 OAuth 令牌与官方 ZenMoney API v8 通信（POST /v8/diff/ 同步协议和 POST /v8/suggest/），例如通过 Zerro 获取的令牌。

这是一个非官方项目，与 ZenMoney 或 Zerro 无关。你的令牌和数据都保留在你的设备上。

快速开始

要求：Node.js >= 22。

1. 获取令牌：打开 https://zerro.app/token，使用你的 ZenMoney 账户登录，然后复制显示的令牌。
2. 验证令牌：ZENMONEY_TOKEN=... npx -y mcp-server-zenmoney --check 会输出 OK: <login>, main currency …, N active accounts, M transactions（否则退出代码为 1，并显示原因）。
3. 将服务添加到你的 Agent（见下文）。

即使没有令牌，服务也能启动；此时每个工具都会说明如何配置令牌。

连接到 Agent（stdio）

Claude Code

claude mcp add zenmoney -e ZENMONEY_TOKEN=YOUR_TOKEN -- npx -y mcp-server-zenmoney

Claude Desktop / Cursor / 大多数 MCP 客户端

claude_desktop_config.json、~/.cursor/mcp.json 等：

{
  "mcpServers": {
    "zenmoney": {
      "command": "npx",
      "args": ["-y", "mcp-server-zenmoney"],
      "env": { "ZENMONEY_TOKEN": "YOUR_TOKEN" }
    }
  }
}

omp

用户级配置 ~/.omp/agent/mcp.json（或项目级 .omp/mcp.json），位于 mcpServers 中：

"zenmoney": {
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "mcp-server-zenmoney"],
  "env": { "ZENMONEY_TOKEN": "${ZENMONEY_TOKEN}" }
}

omp 会展开 ${VAR} 占位符，因此令牌可以保留在 Shell 环境中。然后运行 /mcp reload。

避免将令牌写入配置文件

umask 077 && printf '%s' 'YOUR_TOKEN' > ~/.config/zenmoney-token

并使用 "env": { "ZENMONEY_TOKEN_FILE": "~/.config/zenmoney-token" } 替代 ZENMONEY_TOKEN。

只读模式

将 "ZENMONEY_READ_ONLY": "true" 添加到 env，或将 --read-only 添加到 args。这样将完全不注册写入工具。

HTTP 模式

ZENMONEY_TOKEN=... npx -y mcp-server-zenmoney --http --port 3000

• MCP 端点（Streamable HTTP）：http://127.0.0.1:3000/mcp；GET /health 返回 {"ok":true}；其他路径均返回 404。
• 默认绑定地址为 127.0.0.1。对于回环绑定地址（127.0.0.1、localhost、::1），会针对 DNS 重绑定进行 Host/Origin 验证。
• 除非设置了 MCP_HTTP_TOKEN，否则会拒绝任何其他 --host / MCP_HTTP_HOST 值。设置令牌后（无论绑定到哪个地址），客户端都必须发送 Authorization: Bearer <MCP_HTTP_TOKEN>，否则会收到 401。这是一个单用户服务：持有该令牌的人即可访问你的 ZenMoney，因此请将它保存在专用网络中。

配置

变量 / 标志	默认值	含义
ZENMONEY_TOKEN	—	来自 https://zerro.app/token 的 ZenMoney API 令牌
ZENMONEY_TOKEN_FILE	—	包含令牌的文件（当 ZENMONEY_TOKEN 为空时使用；会展开 ~）
ZENMONEY_READ_ONLY / --read-only	false	1/true/yes/on 时仅注册读取工具
ZENMONEY_SYNC_TTL	30	下次调用工具前，数据重新同步的等待秒数
ZENMONEY_CACHE_DIR	$XDG_CACHE_HOME/mcp-server-zenmoney，否则为 ~/.cache/mcp-server-zenmoney	快照缓存目录
ZENMONEY_CACHE	on	0/false/no/off 时仅在内存中保留数据
ZENMONEY_API_URL	https://api.zenmoney.ru，回退到 https://api.zenmoney.app	固定使用单个 API 源
MCP_TRANSPORT / --http	stdio	http 启用 Streamable HTTP 服务
MCP_HTTP_HOST / --host	127.0.0.1	HTTP 绑定地址
MCP_HTTP_PORT / --port	3000	HTTP 端口
MCP_HTTP_TOKEN	—	HTTP 客户端必须发送的 Bearer 令牌；绑定到非回环地址时必填
--check	—	使用配置的令牌同步一次，打印单行摘要后退出
--help、-h / --version、-v	—	打印用法说明 / 版本

CLI 标志的优先级高于相应的环境变量。

工具

读取工具（始终注册，并标注 readOnlyHint）：

工具	用途
get_overview	从这里开始：今天的日期、主货币、净资产、账户余额、本月收入／支出、即将进行的计划操作、数据新鲜度
list_accounts	账户及其余额（也以主货币表示）、信用额度、银行和标记
list_categories	类别树，包含类别类型（支出／收入／两者）和过去 12 个月的使用次数
list_payees	按使用频率排序的已知收款方，包含最近日期和常用类别
list_transactions	筛选、分页搜索交易，并汇总所有匹配项的收入／支出
summarize_transactions	按类别、父类别、收款方、账户或日／周／月／年汇总；现金流请使用 measure=both
get_budget	按类别显示月度预算与实际支出、剩余金额、使用百分比及仍计划进行的操作
list_planned	日期范围内仍待处理的计划／定期操作及预期总额
list_debts	按人显示债务余额（正数 = 对方欠你）；可选查看某人的债务交易
suggest_category	根据 ZenMoney 和你自己的历史记录，为收款方名称推荐类别／商家
sync	立即从 ZenMoney 拉取更改；full=true 会重新下载所有内容

写入工具（只读模式下不会注册）：

工具	用途
create_transactions	记录最多 50 笔支出、收入、转账或债务操作；自动分类并提示重复项
update_transactions	编辑金额、账户、类别、收款方、备注、日期、原始金额；以及转账目标。无法更改类型
delete_transactions	按 ID 软删除交易
restore_transactions	将已删除的交易恢复为副本，并分配新的 ID
create_category	创建类别或子类别（仅一层嵌套）
update_category	重命名、移动、更改类型、预算计入状态、必需标记或归档状态
delete_category	删除类别，并将其交易和计划操作移至 move_to，或取消分类
set_budgets	为各类别设置精确的月度预算：total 或 uncategorized；设为 0 即移除
create_account	创建现金、银行卡、支票或电子货币账户
update_account	重命名、归档、设置是否计入余额、储蓄标记和信用额度
adjust_account_balance	通过记录一笔更正收入／支出，使余额与实际余额一致

写入工具带有 MCP 注解：创建类工具不会造成破坏（destructiveHint: false）；编辑／删除类工具具有破坏性（destructiveHint: true），因此支持这些提示的客户端可以请求确认。

create_transactions、update_transactions、delete_transactions、delete_category 和 set_budgets 支持 dry_run: true：它们会解析所有内容并返回预期结果（对于更新，每笔交易都会返回 before／after），但不会向 ZenMoney 发送任何内容。

提示词

支持 MCP 提示词（例如斜杠命令）的客户端可使用三个仅编排上述工具的工作流：

提示词	参数	功能
monthly_review	month (YYYY-MM)	收入、与上月相比的支出、预算状态、大额交易、即将到来的付款、建议
categorize_transactions	period	为尚未分类的交易建议类别，并在确认后应用（先进行试运行）
plan_budget	month (YYYY-MM)	根据过去三个月的数据和计划付款提出预算建议，并在确认后使用 set_budgets 应用

约定

这些内容也会作为服务指令发送给 Agent。

• 金额始终为正数；type 表示方向：expense（支出）、income（收入）、transfer（自有账户之间的转账）、debt_out（借钱给他人或偿还借款）、debt_in（收到借款或他人还款）。
• 账户和类别可以通过名称引用（不区分大小写和表情符号；唯一的子字符串也有效）、"Parent / Child" 类别路径或 ID 引用。账户也可以通过银行卡末尾数字引用（至少 4 位）。
• 货币使用 ISO 代码（RUB、USD、KZT 等）。日期格式为 YYYY-MM-DD。
• 查询工具接受 period：today、yesterday、this_week、last_week、this_month、last_month、this_quarter、last_quarter、this_year、last_year、last_7_days、last_30_days、last_90_days、last_12_months（每周从周一开始；date_from/date_to 可覆盖任一端点）。
• 报告使用 ZenMoney 当前汇率，以主货币计价；与 ZenMoney 一样，除非另有要求，否则只统计纳入余额的账户。汇总中不包含转账和债务。list_transactions 返回的总额遵循相同规则（纳入余额且未删除），即使列出的交易包含不纳入余额的交易或已删除交易。
• 新交易缺少支出/收入类别时，会先根据此收款方的历史记录填充，然后使用 ZenMoney 建议服务（仅限有效且类型匹配的类别）。如果新交易与现有交易匹配（日期、类型、账户和金额相同），会发出重复警告；但仍会记录该交易。
• update_transactions 中的 category 会替换主类别并保留次要标签；null 会使交易不分类。将交易转移到使用其他货币的账户时，必须提供新的 amount。仅更改同币种转账的 amount 时，除非收款金额不同（存在手续费），否则会同时更新转账两侧；若存在手续费，则保留收款金额。
• 每次写入都会先与 ZenMoney 同步，并且一次只处理一项，因此不会覆盖刚刚在应用中所做的编辑，且并行工具调用不会相互覆盖。如果应用中已删除所引用的类别/商户，这些引用会从推送的对象中移除，而不会导致整个批次失败。
• 如果 ZenMoney 接受了写入但响应丢失（超时），工具会提示更改可能已保存，也可能未保存；下次调用会重新同步，因此重试会得到重复警告，而不会悄悄创建重复项。
• 删除为软删除。ZenMoney 无法原位撤销删除，因此 restore_transactions 会为每笔交易创建一个新 ID；再次恢复同一笔交易时不会执行任何操作，并会指向现有副本。
• 预算：set_budgets 设置精确金额（启用锁定）；0 会移除预算。未锁定的预算（在应用中设置）也会包含本月的计划操作，与 ZenMoney 一致。会遵循个人资料中设置的每月起始日。不对月份之间的结转进行建模。
• Zerro 隐藏的 🤖 [Zerro Data] 账户及其关联提醒在任何地方都会被忽略。

示例提示词

• “10 月过得怎么样？最大的类别有哪些？与 9 月相比有什么异常吗？”
• “添加：今天从 Kaspi Gold 支付 12 450 KZT 给 Magnum，类别为杂货。”
• “将上个月所有 Yandex Go 行程重新归类到 Transport / Taxi。”
• “把本月预算复制到下个月，但将 Restaurants 提高到 80 000。”
• “谁欠我钱？总共欠多少？”
• “接下来两周安排了哪些付款？”
• “我的现金钱包实际有 23 000；修正余额。”

数据、隐私与同步

• 服务会通过 /v8/diff/ 同步 ZenMoney 数据库的本地副本：首次使用时完整下载，此后增量获取差异。数据超过 ZENMONEY_SYNC_TTL 秒后，会在工具运行前自动刷新；sync 可强制刷新。
• 副本会持久化到 <cache dir>/snapshot-<hash>.json（目录权限为 0700，文件权限为 0600）。文件名是令牌和 API 源的哈希；令牌本身绝不会写入磁盘。快照确实包含你的财务数据。设置 ZENMONEY_CACHE=off 可将所有数据保留在内存中。
• API 源：优先使用 https://api.zenmoney.ru；如果在任何请求成功前该源拒绝令牌，则尝试 https://api.zenmoney.app。ZENMONEY_API_URL 可固定使用单个源。
• ZenMoney 返回 HTTP 401 表示令牌已失效：请前往 https://zerro.app/token 获取新令牌。
• “今天”和默认日期使用进程时区；如果 Agent 主机运行在其他时区，请在服务的 env 中设置 TZ（例如 TZ=Asia/Almaty）。
• 不再使用的令牌对应的快照仍会留在缓存目录中；更换令牌后，请删除旧的 snapshot-*.json 文件。
• 日志仅输出到 stderr。

限制

• 可以读取计划（定期）操作，但无法创建或编辑。
• 无法创建贷款和存款账户；银行同步账户由 ZenMoney 自行创建。
• 不能直接编辑余额；adjust_account_balance 会记录一笔更正交易。
• 报告中的货币换算使用当前汇率，而非历史汇率。
• 不会计算 Zerro 的信封预算结转。

开发

git clone https://github.com/krax1337/mcp-server-zenmoney && cd mcp-server-zenmoney
npm install         # also builds dist/
npm run typecheck   # tsc --noEmit
npm test            # vitest; offline, against an in-repo fake ZenMoney server in test/
node dist/index.js  # run the local build

发布：更新 package.json 和 server.json 中的 version，然后推送 vX.Y.Z 标签。Publish 工作流会运行测试，通过 Trusted Publishing（无需令牌，并带有来源证明）发布到 npm，并以 io.github.krax1337/mcp-server-zenmoney 的名称发布到 MCP Registry。

源代码目录结构：

• src/index.ts — 入口点，stdio 和 HTTP 传输
• src/config.ts — 环境变量和 CLI 标志
• src/server.ts — MCP 服务和 Agent 指令
• src/prompts.ts — MCP 提示词（monthly_review、categorize_transactions、plan_budget）
• src/tools/ — MCP 工具（read.ts、write.ts、共享模式和上下文）
• src/zenmoney/ — API 客户端（api.ts）、同步存储和缓存（store.ts）、账本语义（ledger.ts）、分析（analytics.ts）、写入构建器（writes.ts）、日期和类型

许可证

MIT