Beanquery MCP

Beancount MCP Server 是 Model Context Protocol (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) 与语言模型提供商 (LLM) 交互，因此可能会将您的 Beancount 账本的部分内容（包括可能机密或私人的财务信息）传输给第三方服务。

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

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

建议：

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

[!CAUTION] 您有责任保护您的财务数据。不要共享您不希望暴露的账本。

设置

前提条件

• 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. 打开一个 pull request。

许可证

此项目已获得 MIT 许可证的许可。 有关详细信息，请参见 LICENSE 文件。