🚀 豆汁查询 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 文件。