runBqlQuery
对余额、交易和账户运行 BQL（Beancount Query Language）查询。
Model Context Protocol
让账本，融入对话。
把 Beancount 接入你熟悉的 AI 工具。询问财务状况、处理账本文件，让每次变更都能在 Git 中追溯。
直接提问
从一个问题开始，沿着答案追溯到账本。
答案的依据
runBqlQuerySELECT sum(position) WHERE account ~ 'Assets|Liabilities'Beancount
适用于兼容 MCP 的客户端
- Claude Code
- Claude Desktop
- Cursor
- Windsurf
- Zed
连接你已经在用的客户端
选择客户端、添加服务器，再授权访问一本账本。
Claude Code
在你的终端中运行这一条命令。
打开 Claude Code，运行 /mcp 完成身份验证。登录 Web Beancount，然后选择你的账本。
批准一次。凭据将从此自动刷新。
终端
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 账户，授权访问指定的一本账本。
还没有 Web Beancount 账户？ 在 beancount.io 注册 ——你的账本只需一次 git push。
AI 能做什么
服务器为你的账本、API 密钥和银行连接提供专注的工具——账本动词如下所示。AI 会组合它们：发现你的文件结构、读取上下文、查询答案、提出编辑建议。
账本、API 密钥和银行工具。你的客户端决定如何使用它们。
listLedgerFiles
浏览账本仓库的目录结构。
readLedgerFiles
读取你的 .beancount 文件和其他账本文档的内容。
editLedgerFiles
在原子 git 提交中创建、更新、替换或删除文件。
你的账本，安全守护
一个拥有你的账本写入权限的 AI，是靠设计而非承诺来赢得信任的。
账本级 OAuth 2.1
一个会话仅针对一个账本授权。为个人账本创建的会话无法触碰你的企业账本——影响范围，有限。
预演预览
editLedgerFiles 支持 dry_run 模式，该模式在不写入任何内容的情况下验证并预览确切更改，因此你的客户端可以先显示差异。
每次编辑都是一次 git 提交
更改会以真实提交（"AI edit: …"）的形式写入你的账本仓库——这是一份完整的审计轨迹，你可以使用标准 git 工具查看和回滚。
无状态服务器
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 实际上能对我的账本做什么？
服务器提供专注的工具族——beancount.io/.well-known/ 下的机器可读发现清单列出了当前集合。账本工具运行 Beancount Query Language 查询（runBqlQuery）、浏览仓库（listLedgerFiles）、读取账本文档（readLedgerFiles），以及以原子 git 提交创建、更新或删除文件（editLedgerFiles，带 dry_run 预览模式）。其他工具管理 API 密钥（list、mint、revoke——minting 需要付费计划且需 OAuth 授权，而非 API 密钥）以及银行连接和导入（stage、submit 或 discard 交易；全新银行在浏览器中链接，而非通过 MCP）。AI 组合它们来回答问题并提出编辑建议。
AI 能在不知情的情况下修改我的账本吗？
编辑通过 editLedgerFiles 工具进行。dry_run 模式预览计划中的文件操作而不提交任何内容，而你的客户端是否在真实提交前询问取决于客户端。每次提交的更改都会成为真实的 git 提交——一个完整的审计追踪，你可以使用标准 git 工具回退。提交路径可能写入后报告验证错误，因此请先预览，事后验证账本。
我的数据会发送给第三方吗？
你的账本数据会经过 Web Beancount 后端，以工具结果的形式返回给 AI 客户端。你选择的 AI 模型也会接收这些结果，因此模型提供商的数据政策同样适用。每个获授权的会话只能访问一本账本。