# Beancount MCP：将你的账本连接到 AI 助手

问问你的 AI 助手，上个月花了多少钱、哪些账户需要对账，或者某笔交易该归入何处。Beancount MCP 让它能够访问你托管账本的查询、账户和源文件，从而基于你的账本工作，并展示其答案背后的依据。

![一台粘土笔记本电脑连接着一本打开的绿色账本，一个收据放在审阅托盘里，旁边的链接方块代表了 Git 历史。](/img/blog/beancount-mcp/hero.webp)

拥有写入权限后，助手还可以添加交易和更新账本文件。你可以让它预览支持的编辑、审阅提议的条目，并在更改后检查账本。

MCP 代表模型上下文协议（Model Context Protocol）：一种将 AI 应用连接到外部工具和数据的标准。此连接适用于托管在 **Beancount.io** 上的账本。你助手的回答反映了其中记录的交易和价格；连接 MCP 并不会自动使这些记录保持最新。

## 连接你的 AI 客户端

使用支持通过 **Streamable HTTP** 进行远程 MCP 的客户端。服务器 URL 为：

```text
https://beancount.io/api-gateway/mcp
```

### Claude Code

从终端添加服务器：

```bash
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcp
```

打开 Claude Code，运行 `/mcp`，选择 `beancount`，并按照其身份验证流程操作。登录 Beancount.io 并查看请求的权限。返回 `/mcp` 确认连接。有关客户端特定的详细信息，请参阅 [Claude Code 的 MCP 说明](https://code.claude.com/docs/en/mcp)。

同意页面允许你将访问限制为**一个账本**，或明确选择**所有可访问的账本**。限制为单一账本是一个有用的起点。若授予更广泛的访问权限，请告诉助手要使用哪个账本，例如 `alice/personal`；账本工具每次调用时都必须指明其目标。

### Claude Desktop 和网页版 Claude

打开 **Customize → Connectors**，选择 **Add custom connector**，输入服务器 URL，并连接你的 Beancount.io 账户。在你要使用它的对话中启用该连接器。组织账户可能需所有者先添加连接器。请遵循 [Claude 的远程连接器指南](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)。

### Cursor

将服务器添加到你的个人 `~/.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "beancount": {
      "url": "https://beancount.io/api-gateway/mcp"
    }
  }
}
```

当 Cursor 请求时完成 OAuth 登录，然后检查服务器的工具是否可用。 [Cursor 的 MCP 文档](https://cursor.com/docs/mcp) 涵盖了配置和工具批准设置。

### 个人 API 密钥

对于接受 bearer 凭据的客户端，你可以先在 [设置 → 个人访问令牌](https://beancount.io/settings/api-keys) 中创建个人 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`，显示提议的条目和文件差异，然后等待我的确认。

如果这些账户已开设，提议的条目将如下所示：

```beancount
2026-09-15 * "Cafe" "Coffee"
  Expenses:Food   4.50 USD
  Assets:Cash    -4.50 USD
```

使用你账本中的账户名称，然后完成审阅：

1. 检查预览中的日期、金额、账户和目标文件。
2. 确认你希望助手应用的确切更改。
3. 让它运行 `checkLedger`，并报告提交结果和任何错误。

`appendLedgerText` 默认拒绝新的验证错误。一般文件更改使用 `createLedgerFiles`、`updateLedgerFiles` 和 `deleteLedgerFiles`，它们各自在一次 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 客户端提供账本功能，并使用该客户端的对话、模型和批准设置。

**为什么我能看到工具却无法使用？**

工具目录包含你的凭据可能不允许的操作。检查错误和已授予的权限。不受限制的凭据还需要为账本工具指定明确的账本目标。

连接你的账本，从一个你可以对照账本验证的问题开始。保留查询和答案，然后在需要帮助维护账本时添加写入权限。
