金大哥 - beanquery-mcp MCP 详情

article

README

🚀 豆汁查询 MCP 服务器

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

🚀 快速开始

本服务器处于实验阶段，可能会有重大更改。建议在开发环境中使用，并提供反馈以进一步改进。一个生成的示例分录文件可以在 sample.bean 中找到。

✨ 主要特性

对接 Model Context Protocol (MCP)，实现 AI 助手与 Beancount 分录文件的标准化通信。
利用 Beancount 查询语言 (BQL) 和 beanquery 工具，对 Beancount 格式的财务数据进行无缝查询和分析。

📦 安装指南

先决条件

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

💻 使用示例

运行服务器

开发模式

使用 MCP Inspector 测试和调试您的服务器：

mcp dev server.py

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

可用资源和工具

工具

设置分录文件：设置 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 发送的数据，确保符合您的隐私和安全要求。

⚠️ 重要提示 您负责保护您的财务数据。不要共享您不介意公开的分录文件。

🔧 技术细节

贡献指南

创建功能分支

git checkout -b feature/新功能名

提交代码

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

创建拉取请求

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

📄 许可证

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

beanquery-mcp