Beanquery MCP

Beancount MCP服务器是一个实验性的实现，基于模型上下文协议（MCP），旨在与Beancount账本文件进行交互。该服务器利用了Beancount查询语言（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交互的截图，请参见这里。

⚠️ 隐私警告

此工具通过模型上下文协议（MCP）与语言模型提供商（LLMs）进行交互，因此可能会将您的Beancount账本的部分内容——包括可能的机密或私人财务信息——传输给第三方服务。

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

• 您的账本包含敏感数据（例如客户姓名、工资详情、健康相关费用）。
• 您正在使用云托管或非自托管的LLM后端。

建议：

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

[!CAUTION] 您负责保护自己的财务数据。不要分享您不愿意公开暴露的账本。

设置

先决条件

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

使用方法

运行服务器

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 m
     cp 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. 分叉仓库。
2. 创建功能分支：

   git checkout -b feature-name
   

3. 提交您的更改：

   git commit -m "添加功能描述"
   

4. 推送到您的分支：

   git push origin feature-name
   

5. 打开拉取请求。

许可证

本项目采用MIT许可证。详情请参阅LICENSE文件。