Beanquery MCP

Beanquery MCP

Beancount MCP サーバーは、Beancountの台帳ファイルと連携するために設計された、Model Context Protocol（MCP）の実験的な実装です。Beancount Query Language（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の操作を展開したスクリーンショットは、こちらをご覧ください。

⚠️ プライバシーに関する警告

このツールは、Model Context Protocol（MCP）を介して言語モデルプロバイダー（LLM）と連携するため、Beancountの台帳の一部（機密情報や個人の財務情報を含む可能性があります）がサードパーティのサービスに送信される場合があります。

特に、以下の場合はこのツールを慎重に使用してください。

• 台帳に機密データ（クライアント名、給与の詳細、健康関連の支出など）が含まれている場合。
• クラウドホスト型またはセルフホストではないLLMバックエンドを使用している場合。

推奨事項：

• テスト用台帳では機密データをマスキングするか、削除してください。
• 可能な場合はセルフホスト型LLMを使用してください。
• MCP経由で送信されるデータを確認し、プライバシーおよびセキュリティ要件に準拠していることを確かめてください。

注意

財務データの保護はご自身の責任です。公開しても問題ないと思える台帳以外は共有しないでください。

セットアップ

前提条件

• 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. リポジトリをフォークします。
2. 機能ブランチを作成します。

   git checkout -b feature-name
   

3. 変更をコミットします。

   git commit -m "Add feature description"
   

4. ブランチにプッシュします。

   git push origin feature-name
   

5. プルリクエストを作成します。

ライセンス

このプロジェクトはMITライセンスのもとで公開されています。詳細についてはLICENSEファイルをご覧ください。