Beanquery MCP

Beanquery MCP

Beancount MCP 服务是 Model Context Protocol (MCP) 的实验性实现，旨在与 Beancount 账本文件交互。该服务借助 Beancount Query Language (BQL) 和 beanquery 工具，可无缝查询和分析以 Beancount 格式存储的财务数据。通过集成 MCP，该服务可促进 AI 助手与 Beancount 账本之间的标准化通信，提升财务数据的可访问性和实用性。

注意：此服务仍处于实验阶段，可能会发生重大变更。建议在开发环境中使用，并提供反馈以便进一步改进。

生成的示例账本见 sample.bean

可用资源和工具

• 工具：
  • set_ledger_file：设置用于查询的 Beancount 账本文件（若未通过环境变量设置）。
  • run_query：对已加载的 Beancount 文件运行 BQL 查询。
• 资源：
  • beanquery://tables：获取 BQL 可访问的表列表。
  • beanquery://accounts：获取已加载的 Beancount 文件中的账户列表。

使用 Claude.ai 的示例

如需查看展开后的 MCP 交互截图，请参见此处。

⚠️ 隐私警告

此工具通过 Model Context Protocol (MCP) 与大语言模型（LLM）提供商交互，因此可能会将 Beancount 账本的部分内容（包括可能保密或私密的财务信息）传输至第三方服务。

请谨慎使用此工具，尤其是在以下情况下：

• 账本包含敏感数据（例如客户姓名、薪资详情、医疗相关开支）。
• 使用云托管或非可自托管的 LLM 后端。

建议：

• 在测试账本中屏蔽或删去敏感数据。
• 尽可能使用可自托管的 LLM。
• 检查通过 MCP 发送的数据，确保符合隐私和安全要求。

注意

您有责任保护自己的财务数据。请勿分享您不愿公开的账本。

设置

先决条件

• Python 3.10 或更高版本
• 用于管理 Python 项目的 uv（推荐）

使用方法

运行服务

1. 开发模式： 使用 MCP Inspector 测试和调试服务：

   mcp dev server.py
   

2. Claude Desktop 集成： 将服务安装到 Claude Desktop：

   mcp install server.py
   

   • 快速开始：

     uv run mcp install server.py -v BEANCOUNT_LEDGER=$(pwd)/sample.bean --with beancount --with beanquery
     

   • 自定义名称：

     uv run mcp install server.py --name "Beanquery MCP Server" --with beancount --with beanquery
     

   • 环境变量：

     uv run mcp install server.py -v BEANCOUNT_LEDGER=/path/to/your/ledger.bean --with beancount --with beanquery
     uv run mcp install server.py -f .env --with beancount --with beanquery
     

测试

使用 pytest 运行测试套件：

pytest server_test.py

贡献

1. Fork 此仓库。
2. 创建功能分支：

   git checkout -b feature-name
   

3. 提交更改：

   git commit -m "Add feature description"
   

4. 推送到您的分支：

   git push origin feature-name
   

5. 发起拉取请求。

许可证

此项目采用 MIT License。详情请参见 LICENSE 文件。