Beancount MCP（模型上下文协议）服务器

对于坚持复式记账、使用Beancount管理个人财务的用户来说，查询账目和录入交易往往需要在命令行和文本编辑器之间来回切换。如果能让你的AI助手直接帮你执行Beancount查询，甚至根据你的指令生成并提交新的交易记录，是不是能极大地提升记账的效率和乐趣？这正是beancount-mcp所带来的改变。

beancount-mcp是一个模型上下文协议服务器，它连接了强大的复式记账工具Beancount与你的AI助手。通过这个服务器，你的AI可以执行Beancount查询，读取你的账目数据，甚至可以将你口述的消费记录格式化成Beancount交易并提交到账本中。

项目基本信息

一、项目介绍

beancount-mcp是一个简洁而专注的MCP服务器。它的核心目标是与Beancount账本文件进行交互，提供两种主要能力：查询和提交。

通过查询功能，你的AI可以读取并分析Beancount账本中的数据。例如，你可以问“我这个月餐饮支出一共多少？”或者“我的资产净值在过去三个月的变化趋势是什么？”AI会将这些自然语言问题转化为Beancount查询语句（如bean-query），执行后并将结果解释给你。

通过提交功能，你可以用自然语言告诉AI一笔新的消费，比如“今天午饭花了50元，从餐饮支出账户扣，用信用卡支付的。”AI会理解这句话，将其格式化成标准的Beancount交易格式，并追加到你的账本文件中。这极大地简化了日常记账的录入过程。

该服务器通过uvx命令即可运行，无需复杂的安装。它支持stdio和SSE两种传输方式，可以方便地集成到Claude Desktop等MCP客户端中。

二、核心优势

用自然语言查询财务数据：你不需要记忆复杂的Beancount查询语法，也不需要打开终端手动输入命令。只需要像和朋友聊天一样，问你的AI助手关于你财务状况的任何问题。服务器会负责将你的问题转化为精确的查询并执行。

通过对话完成记账录入：记账最大的痛点就是录入。每一笔消费都需要按照严格的格式记录日期、账户、金额、描述。beancount-mcp允许你用“我今天买了一本书，花了68元”这样简单的句子完成录入。AI会帮你生成正确的交易格式。

开源透明，完全掌控数据：所有的代码都是开源的，你的账本文件始终保留在你自己的电脑上。这意味着你的财务数据永远不会离开你的控制。

轻量级，开箱即用：作为一个Python项目，它可以通过uvx直接运行，不需要克隆代码或手动安装依赖。对于熟悉Python和Beancount的用户来说，配置过程非常简单。

三、适用场景

场景一：日常记账录入。这是最常用的场景。每次消费后，你可以发给AI一条消息：“午餐支出45元，从餐饮预算账户扣，使用支付宝。” AI会生成对应的Beancount交易并追加到你的账本中。

场景二：快速财务概览。你可以随时提问：“我这个月总支出是多少？”“我的主要消费类别是什么？”“我的信用卡账户余额还有多少？” AI会执行查询并告诉你答案。

场景三：生成财务报告。你可以要求AI：“帮我查一下过去三个月的餐饮支出趋势，按月份汇总。” AI会执行相应的查询，并可以配合其他MCP工具将结果生成图表或报告。

场景四：预算监控。你可以设置AI定期检查：“我这个月的餐饮预算还剩多少？” 或者当某类支出接近预算时，让AI发出提醒。

四、安装教程

使用beancount-mcp前，你需要有一个Beancount账本文件（通常是.bean或.beancount文件）。如果你还没有，需要先学习Beancount的基础知识并创建一个。

第一步：确保环境

• 安装Python 3.8或更高版本
• 安装uv工具（推荐）或pip
• 准备你的Beancount账本文件，记下它的完整路径

第二步：配置MCP客户端

我们以Claude Desktop为例。找到其配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

使用文本编辑器打开该文件，添加以下配置。请务必将PATH_TO_YOUR_LEDGER替换为你的Beancount账本文件的绝对路径。

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

注意：如果你不使用uv，也可以使用python -m beancount_mcp的方式，但推荐使用uvx，它会自动处理依赖。

对于Windows用户，如果直接运行遇到问题，可以尝试用cmd包装：

{
  "mcpServers": {
    "beancount": {
      "command": "cmd",
      "args": ["/c", "uvx", "beancount-mcp", "--transport=stdio", "C:\\路径\\到\\你的\\账本.bean"]
    }
  }
}

第三步：重启并验证

保存配置文件，完全退出Claude Desktop并重新启动。现在，你可以尝试提问：“请帮我查一下我的账本里一共有多少条交易记录。”

如果配置成功，AI会调用相关工具并返回结果。

五、使用示例

配置完成后，你就可以像和你的私人财务助理对话一样，管理你的账目了。

示例一：查询总支出

你问：“我这个月（2026年4月）的总支出是多少？”

AI会构建一个查询，计算所有日期在2026年4月的支出交易总额。

示例二：分类支出汇总

你问：“帮我汇总一下过去三个月，我在‘餐饮’这个类别上的支出。”

AI会执行按类别分组的查询，并返回每个月的餐饮支出金额。

示例三：录入新交易

你说：“记录一笔：昨天买咖啡花了28元，从我的借记卡（Assets:Checking）支付，分类到Expenses:Coffee。”

AI会将这句话解析为Beancount交易格式，并追加到你的账本文件中。

示例四：账户余额查询

你问：“我的信用卡账户（Liabilities:CreditCard）当前余额是多少？”

AI会查询信用卡账户的所有交易，计算出当前欠款金额。

示例五：趋势分析

你问：“过去半年，我的水电费支出有什么变化趋势？”

AI会查询每个月的Utilities支出，并可以用列表或文字描述的形式返回给你。

六、常见问题

问题一：服务器启动后，AI提示找不到uvx命令。

解决方案：这说明uv工具没有正确安装或未添加到PATH。请先运行uv --version确认。如果没有安装，请参考uv的官方文档进行安装（https://docs.astral.sh/uv/）。安装后重启终端和Claude Desktop。

问题二：查询或提交时提示账本文件找不到或解析错误。

解决方案：请检查你在配置文件中提供的账本文件路径是否正确，必须是绝对路径。同时，确认你的账本文件本身没有语法错误，可以尝试在终端中运行bean-check 你的账本文件来验证。

问题三：提交交易时，AI生成的交易格式不正确。

解决方案：Beancount的格式非常严格。如果你给出的描述不够清晰，AI可能会生成格式有误的交易。建议在提问时提供更明确的账户名称。例如，不要说“从我的饭卡扣”，而是说“从Assets:MealCard账户扣”。你可以先让AI生成交易预览，确认无误后再提交。

问题四：这个服务器会修改我的原始账本文件吗？

解决方案：是的，当你使用“提交交易”功能时，服务器会将新的交易追加到账本文件的末尾。建议你定期备份你的账本文件。同时，Beancount本身的设计是追加写入，不会修改历史交易，这保证了数据的安全性和可追溯性。

问题五：我可以在多个客户端中同时使用这个服务器吗？

解决方案：不建议这样做。因为多个客户端可能同时尝试写入同一个账本文件，会导致冲突或数据损坏。最好只在一个MCP客户端中配置和使用该服务器。如果你需要在多处访问数据，可以考虑使用SSE传输模式，并在服务端进行适当的并发控制。

七、总结

beancount-mcp是一个对Beancount用户来说极具实用价值的MCP服务器。它将Beancount强大但略显复杂的查询和录入操作，简化成了与AI的自然语言对话。这极大地降低了记账的操作门槛，让坚持复式记账变得更容易、更有趣。

这个项目的最大魅力在于其整合性和便利性。它将一个优秀的开源复式记账工具（Beancount）与最前沿的AI交互方式（MCP）结合在了一起。对于已经或打算使用Beancount的用户来说，beancount-mcp是一个能让你的财务管理系统如虎添翼的组件。

虽然项目目前的功能还比较基础（查询和提交），但它已经解决了记账流程中最核心的两个痛点。随着项目的迭代，未来可能会增加预算管理、报表生成等更高级的功能。

如果你是一个追求数据自主、热爱复式记账并且乐于尝试新技术的人，我强烈推荐你尝试beancount-mcp。它可能会改变你和你的账本互动的方式。