问问你的 AI 助手，上个月花了多少钱、哪些账户需要对账，或者某笔交易该归入何处。Beancount MCP 让它能够访问你托管账本的查询、账户和源文件，从而基于你的账本工作，并展示其答案背后的依据。
拥有写入权限后，助手还可以添加交易和更新账本文件。你可以让它预览支持的编辑、审阅提议的条目，并在更改后检查账本。
MCP 代表模型上下文协议（Model Context Protocol）：一种将 AI 应用连接到外部工具和数据的标准。此连接适用于托管在 Beancount.io 上的账本。你助手的回答反映了其中记录的交易和价格；连接 MCP 并不会自动使这些记录保持最新。
连接你的 AI 客户端
使用支持通过 Streamable HTTP 进行远程 MCP 的客户端。服务器 URL 为：
https://beancount.io/api-gateway/mcpClaude Code
从终端添加服务器：
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcp打开 Claude Code，运行 /mcp，选择 beancount，并按照其身份验证流程操作。登录 Beancount.io 并查看请求的权限。返回 /mcp 确认连接。有关客户端特定的详细信息，请参阅 Claude Code 的 MCP 说明。
同意页面允许你将访问限制为一个账本，或明确选择所有可访问的账本。限制为单一账本是一个有用的起点。若授予更广泛的访问权限，请告诉助手要使用哪个账本，例如 alice/personal；账本工具每次调用时都必须指明其目标。
Claude Desktop 和网页版 Claude
打开 Customize → Connectors，选择 Add custom connector，输入服务器 URL，并连接你的 Beancount.io 账户。在你要使用它的对话中启用该连接器。组织账户可能需所有者先添加连接器。请遵循 Claude 的远程连接器指南。
Cursor
将服务器添加到你的个人 ~/.cursor/mcp.json：
{
"mcpServers": {
"beancount": {
"url": "https://beancount.io/api-gateway/mcp"
}
}
}当 Cursor 请求时完成 OAuth 登录，然后检查服务器的工具是否可用。 Cursor 的 MCP 文档 涵盖了配置和工具批准设置。
个人 API 密钥
对于接受 bearer 凭据的客户端，你可以先在 设置 → 个人访问令牌 中创建个人 API 密钥。 创建密钥需要付费 Beancount.io 计划。 选择 ledger.read 用于查询，可选择将密钥限制为一个账本，并在显示时复制它。使用客户端的私有凭据设置，将授权头配置为 Authorization: Bearer YOUR_KEY。
将密钥放在共享项目配置之外。OAuth 客户端通过登录流程管理凭据；你无需为该路径创建个人密钥。
从一个支出问题开始
连接后尝试以下内容，将账本名称替换为你自己的：
使用
alice/personal。识别其账户和货币，然后按账户汇总 2026 年 8 月的支出。显示每个总额背后的日期范围和 BQL，保持货币分开，并报告任何账本验证错误。不要更改任何内容。
助手可以通过 listLedgers 发现你的账本，通过 getLedgerContext 了解你的账户名称，并使用 runBqlQueryStructured 运行类型化查询结果。 checkLedger 返回验证错误、条目数量和最新提交。
有用的回答包括账本、期间、货币、总额和支持查询。对于净资产问题，还要要求提供估值方法和所用价格的日期。即使账本通过验证，缺失交易或过时价格也可能改变答案。
通过预览添加交易
对于新条目，appendLedgerText 接受普通的 Beancount 文本，并使用你的账本配置将指令路由到文件。其 dry_run 选项在提交前返回差异和预计验证错误。
例如：
准备一笔 2026 年 9 月 15 日的 4.50 美元咖啡购买，从
Assets:Cash支付，归入Expenses:Food。首先检查这些账户是否存在，并查找匹配的交易。使用appendLedgerText并设置dry_run: true，显示提议的条目和文件差异，然后等待我的确认。
如果这些账户已开设，提议的条目将如下所示：
2026-09-15 * "Cafe" "Coffee"
Expenses:Food 4.50 USD
Assets:Cash -4.50 USD使用你账本中的账户名称，然后完成审阅：
- 检查预览中的日期、金额、账户和目标文件。
- 确认你希望助手应用的确切更改。
- 让它运行
checkLedger，并报告提交结果和任何错误。
appendLedgerText 默认拒绝新的验证错误。一般文件更改使用 editLedgerFiles，它可以在一次 Git 提交中创建、替换、更新或删除文件。其预览也会报告差异和预计错误。检查结果，并在写入后运行 checkLedger：成功提交仍可能包含会计错误。
使用工作流进行例行记账
服务器还提供可复用的 MCP 提示。支持提示的客户端会在其命令或提示选择器中展示这些提示：
| 工作流 | 它帮助你做什么 |
|---|---|
spending-report | 回答支出问题，并提供支持性 BQL，且不涉及账本写入。 |
reconcile-account | 将一个账户与提供的对账单比较，分类差异，并提出缺失条目。 |
close-month | 审阅活跃账户、余额断言、经常性交易和未解决标记。 |
categorize-imports | 审阅暂存的银行交易，并使用现有账户提出分类建议。 |
这些提示会引导助手按照流程操作。它们不会仅因为你选择而自动运行会计作业，也不会授予额外权限。
对账需要一份对账单和期末余额。仅凭干净的验证结果无法确定每笔交易都已记录。请助手识别任何无法验证的内容，并在报告中保留这些未解决问题。
对于银行导入，先在 Beancount.io 中关联银行。读取连接详情需要管理权限；提交暂存交易需要写入权限以及对该银行连接的适当访问。在授权提交前审阅提议的分类和重复项。
了解访问和数据处理
该连接的权限决定助手可以做什么：
| 权限 | 访问范围 |
|---|---|
ledger.read | 查询和读取账本数据。 |
ledger.write | 读取数据并进行普通账本更改。 |
ledger.admin | 在授权范围内进行读取、写入和管理操作。 |
你对每个账本的现有访问仍然适用。将凭据限制在一个账本上，可防止账本调用针对其他账本；不受限制的凭据可以在你可访问的账本之间选择。OAuth 客户端选择请求哪些权限，因此请在批准前阅读同意页面。
MCP 服务器不会显示人工批准对话框。 你的客户端设置决定了何时在调用工具前询问，并且必须明确请求预览。提供的写入工作流会指示助手等待确认。限制为 ledger.read 的凭据在你想要仅分析而不写入时提供了强制边界。
工具结果（包括查询的交易和助手读取的文件）会进入你 AI 客户端的上下文，并可能由其模型提供商处理。Beancount.io 保留你的账本、Git 历史及操作记录。无状态 MCP 连接并不保证不保留数据；你客户端和提供商的数据政策同样适用。
被撤销的个人 API 密钥会在后续请求中被拒绝。OAuth 访问令牌通常有效一小时；撤销刷新令牌不会立即使已签发的访问令牌失效。在受保护操作运行时，会再次检查账本访问权限。
常见问题
这会在我的笔记本电脑上打开账本吗？
托管端点操作的是你的 Beancount.io 账本。它不会打开本地 .bean 文件，也不需要保持 Fava 浏览器标签页打开。
这与仪表板的 AI 助手有何不同？
仪表板提供自己的聊天界面。MCP 则从外部 AI 客户端提供账本功能，并使用该客户端的对话、模型和批准设置。
为什么我能看到工具却无法使用？
工具目录包含你的凭据可能不允许的操作。检查错误和已授予的权限。不受限制的凭据还需要为账本工具指定明确的账本目标。
连接你的账本，从一个你可以对照账本验证的问题开始。保留查询和答案，然后在需要帮助维护账本时添加写入权限。
