Beanquery MCP

🚀 豆汁查询 MCP サーバー

Beanquery MCP サーバーは、Model Context Protocol (MCP) と接続し、Beancount の仕訳ファイルとやり取りするための実験的な実装です。Beancount Query Language (BQL) と beanquery ツールを利用することで、Beancount 形式で保存された財務データのシームレスなクエリと分析を実現しています。MCP を統合することで、このサーバーは AI アシスタントと Beancount 仕訳ファイル間の標準化された通信を実現し、財務データのアクセス可能性と有用性を向上させています。

⚠️ 重要提示

このサーバーは実験段階にあり、重大な変更が加えられる可能性があります。開発環境で使用し、改善のためのフィードバックを提供することをおすすめします。

生成されたサンプルの仕訳ファイルは sample.bean で見ることができます。

✨ 主な機能

利用可能なリソースとツール

• ツール:
  • 仕訳ファイルの設定: 環境変数で設定されていない場合、Beancount 仕訳ファイルをクエリ用に設定します。
  • クエリの実行: 読み込まれた Beancount ファイルに対して BQL クエリを実行します。
• リソース:
  • beanquery://tables: BQL でアクセス可能なテーブルのリストを取得します。
  • beanquery://accounts: 読み込まれた Beancount ファイル内のアカウントのリストを取得します。

Claude.ai を使用した例

MCP のやり取りを拡張した詳細なスクリーンショットは こちら を参照してください。

⚠️ プライバシー警告

このツールは Model Context Protocol (MCP) を介して言語モデルプロバイダー（LLMs）とインターフェースを持ち、Beancount 仕訳ファイルの一部の内容（機密または敏感な財務情報を含む可能性があります）をサードパーティのサービスに送信する可能性があります。

以下の場合には、このツールの使用には注意が必要です。

• 仕訳ファイルに敏感なデータ（例えば、顧客名、給与詳細、健康関連の支出）が含まれている場合。
• 使用する LLM バックエンドがクラウド上にホストされているか、自ホストではない場合。

💡 使用建议

• テスト用の仕訳ファイルで敏感なデータをマークまたは隠蔽してください。
• 可能な限り自ホストの LLMs を使用してください。
• MCP を介して送信されるデータを確認し、プライバシーとセキュリティの要件を満たしていることを確認してください。

⚠️ 重要提示

あなた自身が財務データの保護に責任があります。公開しても構わない仕訳ファイルのみを共有してください。

📦 インストール

前提条件

• Python 3.10 以上
• uv（Python プロジェクトの管理に推奨）

💻 使用例

サーバーの実行

基本的な使用法

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 サーバー" --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. プルリクエストの説明を記入し、送信します。

📄 ライセンス

このプロジェクトは MIT License に従います。詳細については LICENSE ファイルを参照してください。