Beanquery MCP Server

Beanquery MCP

Beancount MCPサーバーは、 Beancount台帳ファイルとのインターフェース用に設計されたモデルコンテキストプロトコル（MCP）の実験的な実装です。Beancountクエリ言語（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 インタラクションの拡張スクリーンショットについては、ここを参照してください。

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

このツールは、モデル コンテキスト プロトコル (MCP) を介して言語モデル プロバイダー (LLM) とインターフェイスし、Beancount 台帳の一部 (機密情報や個人の財務情報が含まれる可能性があります) をサードパーティのサービスに送信する場合があります。

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

• 元帳には機密データ（例：顧客名、給与の詳細、医療費）が含まれています。
• クラウドホスト型または非セルフホスト型の LLM バックエンドを使用しています。

推奨事項:

• テスト台帳内の機密データをマスクまたは編集します。
• 可能な場合は、セルフホスト型 LLM を使用します。
• MCP 経由で送信されるデータを確認し、プライバシーとセキュリティの要件に準拠していることを確認します。

[!注意] 財務データの保護はお客様の責任です。公開することに抵抗のある元帳は共有しないでください。

設定

前提条件

• Python 3.10以降
• Python プロジェクトの管理にはuvが推奨されます

使用法

サーバーの実行

1. 開発モード: MCP インスペクターを使用してサーバーをテストおよびデバッグします。
   mcp dev server.py
2. Claude デスクトップ統合: Claude デスクトップにサーバーをインストールします。
   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を使用してテスト スイートを実行します。

貢献

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
   git checkout -b feature-name
3. 変更をコミットします。
   git commit -m "Add feature description"
4. ブランチにプッシュします:
   git push origin feature-name
5. プルリクエストを開きます。

ライセンス

このプロジェクトはMITライセンスの下で提供されています。詳細はLICENSEファイルをご覧ください。