beancount-mcp

还在手动记账，月底对着Excel表格发呆？作为一名长期使用Beancount进行复式记账的用户，我深知命令行查询的繁琐和“坚持不下去”的痛苦。直到我遇到了 beancount-mcp，它利用MCP协议将AI助手变成了我的私人会计，现在只需对Claude说“查一下上个月餐饮支出”，数据马上自动呈现。这不仅是工具，更是个人财务管理方式的升级。

项目基本信息

一、项目介绍

beancount-mcp 是一个基于 Model Context Protocol（模型上下文协议）构建的服务器工具，它充当了 AI 助手与 Beancount 账本之间的桥梁[1]。简单来说，它让你可以使用自然语言，通过 AI 来查询账本中的交易记录，甚至向账本中提交新的记账条目。

传统的 Beancount 使用体验高度依赖命令行：你要记住 bean-query 的语法规则，手动编写 BQL 查询语句才能从账本中提取数据。对于非技术人员来说，这个学习门槛相当高。而 beancount-mcp 的核心理念就是打破这个壁垒，让你用最直观的方式与财务数据对话。

目前，该项目支持两种传输模式：标准输入输出和服务器发送事件，可以灵活适配不同类型的 MCP 客户端[3]。无论你使用的是 Claude for Desktop、LobeChat，还是其他支持 MCP 协议的 AI 工具，都能轻松接入。

二、核心优势

采用 MCP 协议进行交互是 beancount-mcp 的最大亮点。在过去，AI 无法直接读取你本地的账本文件，你需要频繁地复制粘贴数据。而现在，beancount-mcp 作为中间层，赋予了 AI 直接操作账本的能力1。这意味着你的财务数据始终保存在本地，无需上传到任何云端服务，在享受 AI 便利的同时，确保了数据的绝对隐私。

从技术角度看，它的部署极为轻量。项目基于 Python 开发，依赖管理工具 uvx 即可一键运行，无需复杂的环境配置1。同时，MIT 开源协议意味着你可以自由使用、修改和分发代码，无论是个人使用还是企业内部集成，都没有任何授权限制。

值得一提的是，社区对此类工具的关注度正在快速上升。虽然 beancount-mcp 本身是一个相对年轻的项目，但它所代表的 AI + 本地财务数据的方向，正在吸引越来越多的开发者和用户参与贡献和完善。

三、适用场景

如果你是 Beancount 的长期用户，厌倦了频繁敲击命令行查询账本，那么 beancount-mcp 能彻底改变你的使用习惯。你可以直接问 AI “今年我在餐饮上的总支出是多少”，或者“展示上个月收入最高的三笔交易”，AI 会自动生成对应的 BQL 查询并返回结果。

如果你正在尝试构建个人 AI 助理工作流，beancount-mcp 可以作为其中的“财务数据模块”。搭配其他 MCP 服务器，你的 AI 助手可以同时管理你的日历、邮件和账本，形成一个完整的自动化管理闭环。

如果你是开发者，想要为自己的开源项目增加 AI 交互能力，beancount-mcp 是一个很好的参考实现。它展示了如何封装一个命令行工具使其支持 MCP 协议，以及如何设计工具的参数和返回格式。

四、安装教程

在开始安装之前，请确保你的系统满足以下要求：Python 3.10 或更高版本，以及 uvx 工具（用于运行 Python 包）1。如果你还没有安装 uv，可以通过 pip 进行安装：pip install uv。

第一步：准备 Beancount 账本文件

你需要有一个现成的 Beancount 账本文件。如果你是从零开始，可以先创建一个简单的 .bean 文件作为测试。假设你的文件路径为 /Users/yourname/main.bean，请记住这个路径，后面会用到。

第二步：配置 MCP 客户端

以 Claude for Desktop 为例，你需要编辑它的配置文件。在 macOS 上，配置文件位于 ~/Library/Application Support/Claude/claude_desktop_config.json；在 Windows 上，位于 %APPDATA%\Claude\claude_desktop_config.json[6]。

打开配置文件，添加以下内容：

{
  "mcpServers": {
    "beancount-mcp": {
      "command": "uvx",
      "args": [
        "beancount-mcp",
        "--transport=stdio",
        "/Users/yourname/main.bean"
      ]
    }
  }
}

请务必将 /Users/yourname/main.bean 替换为你自己的账本文件的实际路径1。

第三步：重启客户端

保存配置文件后，完全退出并重新启动 Claude for Desktop。重启后，你会在输入框附近看到一个锤子或插件的图标，点击它应该能看到 beancount-mcp 提供的工具列表，这表示配置已生效[6]。

针对 LobeChat 用户的配置

如果你使用的是 LobeChat，配置方式略有不同。打开 LobeChat 桌面版，进入“设置 - 默认 Agent”，然后选择“插件设置 - 自定义插件”。点击“快速导入 JSON 配置”，将以下 JSON 粘贴进去即可完成安装1：

{
  "mcpServers": {
    "stdioa-beancount-mcp": {
      "args": [
        "beancount-mcp",
        "--transport=stdio",
        "PATH_TO_YOUR_LEDGER"
      ],
      "command": "uvx"
    }
  }
}

验证安装

配置完成后，你可以尝试在 AI 对话框中输入类似“帮我查一下账本里最新的5笔交易”的指令。如果 AI 能够正确调用工具并返回结果，说明安装已经成功。

五、使用示例

一旦安装配置完成，你就可以通过自然语言与账本进行交互了。以下是几个典型的使用场景和对应的对话示例。

场景一：查询最近的交易记录

你可以直接对 AI 说：“展示我账本里最近发生的10笔交易”。beancount-mcp 会执行相应的查询，AI 会将结果以清晰的列表形式呈现给你，包括交易日期、描述、金额和账户信息。

场景二：按条件筛选数据

复杂的条件筛选也可以一句话完成：“查询今年2月份所有金额大于100元的餐饮支出”。AI 会自动理解你的意图，调用 beancount-mcp 执行 BQL 查询，然后返回符合条件的所有交易。你不需要记住任何 BQL 语法。

场景三：提交新的交易记录

除了查询，你还可以通过对话向账本中添加新的交易。例如：“记录一笔今天的支出：午餐消费48元，从微信支付账户支出，分类为餐饮”。beancount-mcp 会将此交易提交到你的账本文件中。不过请注意，新提交的交易可能需要你手动审核格式，或者按照你的配置自动追加到文件末尾。

场景四：数据分析与汇总

你也可以进行更高层次的财务分析。“帮我统计一下这个月的总支出，并按分类从高到低排序”。AI 会通过多次调用 beancount-mcp 获取必要的数据，然后给出分析结果和可视化建议。

高级提示

由于 beancount-mcp 目前主要提供查询和提交两个核心功能，对于更复杂的分析需求，你可以结合 AI 的数据处理能力。比如，让 AI 先查询出一段时间的全部交易，然后要求它“按星期几统计平均消费金额，找出我花钱最多的那一天”，AI 会在本地计算结果，无需修改账本文件。

六、常见问题

Q: 配置完成后，AI 提示“未找到 MCP 服务器”或工具列表为空怎么办？

A: 首先检查配置文件中的路径是否正确，特别是账本文件的绝对路径。其次，确认 uvx 命令是否可用，可以在终端中手动运行 uvx beancount-mcp --help 测试。最后，确保你完全退出并重启了客户端，而不仅仅是关闭窗口。

Q: 我想使用 SSE 模式而不是 stdio，应该如何配置？

A: 在配置文件的 args 数组中，将 --transport=stdio 替换为 --transport=sse 即可。不过请注意，不同的客户端对 SSE 模式的支持程度不同，stdio 模式是最通用和稳定的选择。

Q: 服务器提示“command not found: uvx”如何解决？

A: 这说明你的系统中没有安装 uv。执行 pip install uv 进行安装。安装完成后，建议重新启动终端和客户端，确保环境变量已更新。

Q: 我可以在远程服务器上运行 beancount-mcp 吗？

A: 理论上可以，但需要注意 MCP 协议目前主要在本地场景下使用。如果你确实需要远程访问，可以考虑通过 SSH 隧道等方式转发端口，但这会增加配置的复杂度。beancount-mcp 被标记为“本地服务”，意味着它更适合运行在客户端所在的设备上1。

Q: 提交交易后，账本文件没有变化？

A: 这种情况通常与权限或文件路径有关。请确保你的账本文件具有写入权限，并且配置文件中的路径是准确无误的。如果问题依旧，可以尝试提交一笔最简单的交易进行测试，例如：“记录一笔1元的测试交易”。

七、总结

beancount-mcp 精准地解决了 Beancount 用户的一大痛点：查询和录入的繁琐操作。通过 MCP 协议，它将强大的 AI 语言理解能力与严谨的本地复式记账系统无缝连接起来。对于已经沉浸在 Beancount 生态中的用户来说，这个项目几乎是一个必装工具，它能显著降低日常使用的摩擦感。

当然，作为一个较新的项目，它仍有完善空间。目前的功能主要覆盖查询和提交，更高级的操作如账户管理、批量导入等尚未支持。另外，MCP 协议本身就是快速演进的标准，未来客户端和服务端的兼容性问题也需要留意。

如果你正在寻找一种让 AI 真正融入个人财务管理的方法，beancount-mcp 是一个值得投入时间尝试的方案。它开源、免费、隐私安全，并且代表了一个明确的技术趋势。不妨花一个小时配置体验一下，你可能会重新爱上记账这件事。