Model Context Protocol
与你已在使用的 AI 工具对话你的账本
Beancount MCP 服务器将你的纯文本账本连接到 Claude Code、Claude Desktop、Cursor、Windsurf、Zed——任何兼容 MCP 的 AI 客户端。无需复制粘贴，无需导出。直接提问即可。
MCP 服务器 URL
https://beancount.io/api-gateway/mcp> 我今天净资产是多少？
⏺ runBqlQuery("SELECT sum(position) WHERE account ~ 'Assets|Liabilities'")
你今天净资产为 128,450.32 USD。
> 添加昨天 42 USD 的团队晚餐并提交
⏺ editLedgerFiles(dry_run: true) → +1 transaction
⏺ git commit a1b4f2e — "AI edit: add team dinner transaction"
完成——已提交到你的账本，并附带完整审计跟踪。
直接提问
回答“我上季度旅行花了多少钱？”以前意味着要懂 BQL 语法、找到正确文件，并将结果复制到聊天中。现在只需一句话。
“我今天净资产是多少？”
从你的实际账本中得出的实时答案——不是猜测。
“总结上个月的支出”
AI 为你编写 BQL 查询并读取结果。
“添加交易并提交到 git”
在你的账本仓库中真实提交，可像其他提交一样回滚。
“我的账本仓库里有什么？”
无需离开编辑器即可浏览和阅读你的.beancount 文件。
AI 能做什么
服务器暴露了四个账本工具。AI 将它们组合使用：发现你的文件结构、读取上下文、查询答案、提议编辑。
runBqlQuery
对余额、交易和账户运行 BQL（Beancount Query Language）查询。
listLedgerFiles
浏览账本仓库的目录结构。
readLedgerFiles
读取你的 .beancount 文件和其他账本文档的内容。
editLedgerFiles
在原子 git 提交中创建、更新、替换或删除文件。
一分钟内完成连接
选择你的 AI 客户端。复制。粘贴。提问。
- 在你的终端中运行这一条命令。
- Claude Code 会打开浏览器窗口——登录并选择要连接的账本。
- 批准一次。凭据将从此自动刷新。
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcp有多个账本？以不同名称再次添加服务器，并在其自己的提示中授权另一个账本：
claude mcp add --transport http beancount-business https://beancount.io/api-gateway/mcp还没有 Web Beancount 账户？ 在 beancount.io 注册 ——你的账本只需一次 git push。
你的账本，安全守护
一个拥有你的账本写入权限的 AI，是靠设计而非承诺来赢得信任的。
账本级 OAuth 2.1
一个会话仅针对一个账本授权。为个人账本创建的会话无法触碰你的企业账本——影响范围，有限。
每次编辑都是一次 git 提交
更改会以真实提交（"AI edit: …"）的形式写入你的账本仓库——这是一份完整的审计轨迹，你可以使用标准 git 工具查看和回滚。
预演预览
editLedgerFiles 支持 dry_run 模式，该模式在不写入任何内容的情况下验证并预览确切更改，因此你的客户端可以先显示差异。
无状态服务器
MCP 服务器只存储你的 AI 客户端对话中已有的内容。你的账本保持原样。
你的整个账本已经是一个 git 仓库。 了解 Git for Beancount 的工作原理
常见问题
什么是 MCP，为什么它对 Beancount 很重要？
MCP（Model Context Protocol）是一个开放标准，让 AI 助手以结构化、安全的方式调用外部工具和数据源。你的 AI 客户端不再猜测或要求你粘贴数据，而是直接连接到你的账本——它查询你的真实数据、读取你的实际文件，并进行精确编辑。
哪些 AI 客户端支持 Beancount MCP 服务器？
任何支持 OAuth 2.1 的 MCP 兼容客户端都可以开箱即用，包括 Claude Code、Claude Desktop、Cursor、Windsurf 和 Zed。不支持 OAuth 2.1 的客户端可以使用在 beancount.io 账户设置中生成的静态令牌进行连接。
如何连接我的账本？
将服务器 URL 添加到客户端的 MCP 配置中。首次使用时，客户端会打开一个浏览器窗口——使用你的 Web Beancount 账户登录并选择要授权的账本。之后客户端会自动存储并刷新凭据。
AI 实际上能对我的账本做什么？
服务器暴露了四个工具：runBqlQuery 执行 Beancount Query Language 查询，listLedgerFiles 浏览你的账本仓库，readLedgerFiles 读取你的账本文档，editLedgerFiles 在原子 git 提交中创建、更新或删除文件。AI 组合它们来回答问题并提出编辑建议。
AI 能在不知情的情况下修改我的账本吗？
编辑通过 editLedgerFiles 工具进行，行为良好的 MCP 客户端会在执行前向你展示这些更改。dry_run 模式在不写入任何内容的情况下预览确切的更改，并且每个提交的更改都是真实的 git 提交——一个完整的审计轨迹，你可以使用标准 git 工具回滚。
我的数据会发送给第三方吗？
你的账本数据流经 Web Beancount 后端，该后端已经管理你的账本，并以结构化结果返回给你的 AI 客户端。会话以账本为范围：每个会话只能访问你授权的账本，MCP 服务器不存储任何超出你的 AI 客户端对话之外的内容。
想知道它是怎么构建的吗？ 在博客上阅读工程 FAQ