豆汁查询 MCP 服务器

Beanquery MCP Server 是一个实验性的实现，旨在对接 Model Context Protocol (MCP)，并与 Beancount 分录文件进行交互。通过利用 Beancount 查询语言 (BQL) 和 beanquery 工具，该服务器实现了对存储在 Beancount 格式中的财务数据的无缝查询和分析。通过集成 MCP，该服务器实现了 AI 助手与 Beancount 分录文件之间的标准化通信，提高了财务数据的可访问性和实用性。

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

一个生成的示例分录文件可以在 sample.bean 中找到。

可用资源和工具

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

使用 Claude.ai 的示例

有关扩展 MCP 交互的详细截图，请参见 here。

⚠️ 隐私警告

此工具通过 Model Context Protocol (MCP) 与语言模型提供程序（LLMs）接口，可能会将您 Beancount 分录文件的部分内容——包括可能机密或敏感的财务信息——传输到第三方服务。

在以下情况下请谨慎使用此工具：

• 您的分录文件包含敏感数据（例如客户姓名、薪资细节、健康相关支出）。
• 您使用的 LLM 后端托管在云中或不是自 hosting。

建议:

• 在测试分录文件中标记或红アク_sensitive 数据。
• 尽可能使用自 hosting 的 LLMs。
• 查看通过 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 服务器" --with beancount --with beanquery
     

   • 环境变量: 使用 -v 或 --env-file 选项指定环境文件路径，例如：

     uv run mcp install server.py --env-file ./env
     

贡献指南

创建功能分支

git checkout -b feature/新功能名

提交代码

git add .
git commit -m "提交信息"
git push origin feature/新功能名

创建拉取请求

1. 在 GitHub 上导航到项目的仓库页面。
2. 点击“新建拉取请求”按钮。
3. 选择源分支（例如 feature/新功能名）和目标分支（通常是 main 或 develop）。
4. 填写拉取请求描述，然后提交。

许可证

本项目遵循 MIT License。有关详细信息，请参阅 LICENSE 文件。