接入 AI 客户端

平台内置 MCP 服务，让 Claude Code、Cursor 等支持 MCP 的 AI 客户端用上平台这一层的账本语义与查询口径：账户与标签目录（含平台维护的描述与启用状态）、经校验的只读 BQL 执行能力，以及平台自己的复盘方法论。有了这些，您可以直接用自然语言提问，例如「我有哪些标签？哪些是目前在用」「上个月支出都花在哪里了？」，回答中的数字来自账本的真实查询结果，而不是模型的估算。

本地已经有一份账本时，让 AI 直接读本地文件当然也行；MCP 的增量在于上面那层语义与口径，以及不必在本机准备查询环境。本服务只读。

一、开始之前

项目	要求
实例	已开放 MCP 端点，地址为您访问 Web 应用的地址 + `/mcp`；自托管需先完成配置，见自托管
客户端	支持 Streamable HTTP 的 MCP 客户端
账号	已登录平台，可在个人设置中创建访问令牌

二、创建访问令牌

登录平台，在右上角用户名下拉菜单中选择 个人设置。
切换到 「访问令牌」 标签页，点击 「新建令牌」。
填写用途（如 Claude Code，最多 64 字）与 有效期（1~3650 天，留空表示长期有效），点击 「创建」。
弹窗会显示完整令牌（形如 bct_xxxxxxxx...）。明文仅显示一次，请立即点击复制并妥善保存；关闭后无法再次查看。
若要停用某个令牌，回到同一页面点 「删除」，使用该令牌的客户端会立即失去访问权限。

令牌等同于账户凭证：不要提交到 Git 仓库，也不要在公开场合粘贴。

令牌也可以交给他人，让对方在他的 Copilot 里只读访问您的账本。共享账本如何参与分析见 Copilot 字段与限制。

三、配置客户端

Claude Code

claude mcp add --transport http beancount-trans \
  https://trans.dhr2333.cn/mcp \
  --header "Authorization: Bearer bct_xxxxxxxxxxxxxxxx"

添加后用 claude mcp list 可确认是否注册成功。

Cursor

编辑 ~/.cursor/mcp.json（也可放在项目内 .cursor/mcp.json）：

{
  "mcpServers": {
    "beancount-trans": {
      "type": "http",
      "url": "https://trans.dhr2333.cn/mcp",
      "headers": {
        "Authorization": "Bearer bct_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

保存后在 Cursor 的 设置 → MCP 中确认该服务已启用。

opencode

用内置命令添加（--global 写入全局配置 ~/.config/opencode/opencode.json）：

opencode mcp add --global --url https://trans.dhr2333.cn/mcp \
  --header "Authorization=Bearer bct_xxxxxxxxxxxxxxxx" beancount-trans

也可直接编辑 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "beancount-trans": {
      "type": "remote",
      "url": "https://trans.dhr2333.cn/mcp",
      "headers": {
        "Authorization": "Bearer bct_xxxxxxxxxxxxxxxx"
      },
      "enabled": true
    }
  }
}

添加后用 opencode mcp list 确认注册成功。Obsidian 的 Copilot 插件以 opencode 作为 agent 后端时，同样读取该全局配置。

其它客户端

凡是支持 Streamable HTTP 的客户端，填写两项即可：

URL：https://trans.dhr2333.cn/mcp
请求头：Authorization: Bearer bct_xxxxxxxxxxxxxxxx

支持 OAuth 2.1 的客户端也可改用浏览器授权流程：此时不必手工创建令牌，客户端会自动打开浏览器让您登录并同意授权。

验证是否接入成功

在客户端中提问，例如「我有哪些账户和标签？」。
正常情况下，客户端会先读取账本上下文，再执行只读 BQL 查询，最后给出带数字来源的回答。

四、能得到什么

接入之后，本地 AI 可以读到平台侧这几类数据，按增量价值从高到低：

账户与标签目录。 平台维护的账户目录与标签目录，含账户的中文描述、标签的层级与描述，以及两者的启用状态；这是把您口语里的类别映射成 account ~ / '完整标签路径' IN tags 条件时的对照表。
服务端查询能力。 run_bql 在平台侧执行，您不必在本机安装 beanquery、也不必自己处理账本结构；平台还把可用语法、推荐写法、常见失败原因与收入/负债的符号约定沉淀成参考交给 AI。
平台的复盘口径。 洞察与月度复盘在 Web 端怎么分析，这两个提示词就怎么交给 AI，本地结论与平台保持一致。
平台持有的账本文件。 read_ledger_file 读取的是平台当前保存的账本原文，适合换一台机器办公、或本地尚未同步账本时使用。

三类原语的差别，本质是上下文怎么送进去：

原语	投递方式	什么时候用
Tools	AI 按需调用	需要最新账本数据时
Resources	客户端挂载为常驻上下文	希望账户/标签目录、BQL 参考不必每轮重复拉取
Prompts	由您主动选择	想按平台口径做一轮复盘时

Tools（由 AI 按需调用）

名称	说明
`get_ledger_context`	获取平台账户目录、标签目录、默认货币与 BQL 用法；查询前通常会先调用
`run_bql`	执行只读 BQL 查询并返回表格结果
`read_ledger_file`	读取账本目录内的单个 `.bean` 文件原文；需要统计时请让 AI 改用 `run_bql`

Resources（客户端可挂载为上下文）

URI	说明
`ledger://accounts`	平台账户目录（账户路径 → 描述）
`ledger://tags`	平台标签目录（完整标签路径 → 描述）
`ledger://bql-reference`	beanquery 实际支持的 BQL 语法与常见失败原因
`ledger://main.bean`	账本入口文件 `main.bean` 原文

Prompts（由您在客户端中主动选择）

名称	说明
`insight_review`	账本洞察复盘：先跨期对比，再追溯 1~2 条线索
`monthly_review`	月度复盘：收入/支出总额、类目结构与环比、大额与异常交易

两个提示词都接受可选的 period 参数（如 2026-08、今年上半年），不填时默认为最近 3 个月。

除了在 Web 端做洞察与月度复盘，也可以把这套口径带到本地按周期复盘：月度用 monthly_review，需要跨期趋势与线索追溯时用 insight_review，季度 / 年度复盘沿用同一批工具与账户 / 标签口径自行扩展取数。这样，本地回顾里的财务数字与平台保持一致，且可追溯到账本。

一、开始之前​

二、创建访问令牌​

三、配置客户端​

Claude Code​

Cursor​

opencode​

其它客户端​

验证是否接入成功​

四、能得到什么​