Beanquery MCP

🚀 豆汁查詢 MCP 服務器

豆汁查詢 MCP 服務器是一個實驗性項目，它能夠對接 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。

📦 安裝指南

先決條件

• 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

📚 詳細文檔

貢獻指南

創建功能分支

git checkout -b feature/新功能名

提交代碼

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

創建拉取請求

1. 在 GitHub 上導航到項目的倉庫頁面。
2. 點擊“新建拉取請求”按鈕。
3. 選擇源分支（例如 feature/新功能名）和目標分支（通常是 main 或 develop）。
4. 填寫拉取請求描述，然後提交。

⚠️ 隱私警告

此工具通過 Model Context Protocol (MCP) 與語言模型提供程序（LLMs）接口，可能會將您 Beancount 分錄文件的部分內容——包括可能機密或敏感的財務信息——傳輸到第三方服務。

在以下情況下請謹慎使用此工具：

• 您的分錄文件包含敏感數據（例如客戶姓名、薪資細節、健康相關支出）。
• 您使用的 LLM 後端託管在雲中或不是自 hosting。

⚠️ 重要提示

您負責保護您的財務數據。不要共享您不介意公開的分錄文件。

💡 使用建議

• 在測試分錄文件中標記或紅アク_sensitive 數據。
• 儘可能使用自 hosting 的 LLMs。
• 查看通過 MCP 發送的數據，確保符合您的隱私和安全要求。

📄 許可證

本項目遵循 MIT License。有關詳細信息，請參閱 LICENSE 文件。