MCP Firebase Server

MCP Firebase サーバー (モデル コンテキスト プロトコル)

このサーバーは、モデルコンテキストプロトコル（MCP）を実装し、Claudeのような大規模言語モデル（LLM）とFirebase（Firestore）間のブリッジとして機能します。MCPの「ツール」としてこれらの操作を公開することで、LLMはFirestoreコレクションの読み取りと書き込みが可能になります。

このサーバーは、公式のmcp Python SDK を使用して構築されています。

前提条件

• Python 3.7 以上 (MCP で使用されるasynccontextmanagerと完全な型ヒント機能には 3.8 以上が推奨)
• Pip (Python パッケージ インストーラー) またはuv (プロジェクト管理用の MCP ドキュメントで推奨)
• Firestore が有効になっている Firebase プロジェクト。
• Firebase サービス アカウント キーの JSON ファイル。

設定

1. **クローン/ダウンロード:**ローカル ディレクトリにサーバー ファイル ( mcp_firebase_server.py )、 requirements.txtなどがあることを確認します。
2. サービスアカウントキー:
   • サーバーを認証するには、Firebase サービス アカウント キーが必要です。
   • オプション1（MCPクライアント構成に推奨）： SERVICE_ACCOUNT_KEY_PATH環境変数を、サービスアカウントJSONファイルの絶対パスに設定します。これは、サーバーがMCPクライアントによって起動される場合に最も柔軟な方法です。
   • オプション2（フォールバック）： SERVICE_ACCOUNT_KEY_PATH環境変数が設定されていない場合、サーバーは自身のディレクトリ（ mcp_firebase_server.pyと同じディレクトリ）にあるserviceAccountKey.jsonというファイルを探します。この方法を使用する場合は、キーファイルの名前を適宜変更してください。
   • **重要:**サービス アカウント キー ファイル (名前やアクセス方法に関係なく) が安全に保管され、プロジェクトにローカル コピーが存在する場合は.gitignoreにリストされていることを確認してください。
3. Firebase ストレージ バケット (オプション):
   • このサーバーでFirebase Storage機能を使用する場合（現在、これを使用するツールはありませんが、将来追加することは可能です）、環境変数FIREBASE_STORAGE_BUCKET Firebaseプロジェクトのストレージバケット名（例： your-project-id.appspot.com ）に設定してください。設定されている場合、サーバーはこの値を読み取り、出力します。
4. 仮想環境を作成する（推奨）： venvを使用する：
   python3 -m venv venv source venv/bin/activate # On macOS/Linux # venv\\Scripts\\activate # On Windows
   または、 uvを使用する場合（新しいプロジェクト用の MCP ドキュメントで推奨されているとおり）：
   uv venv source .venv/bin/activate # Or similar, depending on your uv setup
5. 依存関係のインストール: pipの使用:
   pip install -r requirements.txt
   または、 uvを使用する場合:
   uv pip install -r requirements.txt
   これによりmcp[cli]とfirebase-adminがインストールされます。

サーバーの実行

この MCP サーバーを実行するには、いくつかの方法があります。

1. **直接実行（ run_server.sh経由のstdioトランスポート用）：**サーバーの起動を簡素化するために、 run_server.shスクリプトが提供されています。このスクリプトは、Pythonスクリプトを実行する前に、仮想環境（ venvという名前でプロジェクトルートに存在する場合）の有効化を処理します。まず、スクリプトを実行可能にします。
   chmod +x run_server.sh
   次に、スクリプトを使用してサーバーを実行します。
   ./run_server.sh
   これは、MCP クライアントがサーバーを起動するために通常構成される方法です (以下の「Claude での使用」セクションを参照)。
2. **開発と検査のためのMCP CLIの使用（ mcp dev ）： mcp CLI（ mcp[cli]の一部としてインストールされます）は、開発サーバーと検査ツールを提供します。開発中はこれを強くお勧めします。
   mcp dev mcp_firebase_server.py
   これによりサーバーが起動し、多くの場合、その機能 (ツール、リソース) を検査したりテスト呼び出しを行うための Web インターフェイスが提供されます。

MCPツールの公開

MCPFirebaseServerという名前のこのサーバーは、次のツールを公開します。

1. query_firestore_collection

• **説明 (docstring から):**指定された Firestore コレクションからドキュメントを取得します。
• 引数:
  • collection_name (文字列、必須): クエリする Firestore コレクションの名前。
  • limit (整数、オプション、デフォルト: 50): 返されるドキュメントの最大数。
• 戻り値: (List[Dict[str, Any]]) コレクション内のドキュメントのリスト。各ドキュメントはidフィールドを含む辞書です。エラーが発生した場合は、単一のエラー辞書を含むリストを返します（例: [{"error": "Firestore not initialized..."}]または[{"error": "Failed to query..."}] ）。

2. add_document_to_firestore

• **説明 (docstring から):**自動生成された ID を持つ新しいドキュメントを、指定された Firestore コレクションに追加します。
• 引数:
  • collection_name (文字列、必須): ドキュメントを追加する Firestore コレクションの名前。
  • document_data (オブジェクト/辞書、必須): 追加するドキュメントを表す辞書。
• 戻り値: (Dict[str, Any]) 成功の場合はsuccess (boolean) とid (string) およびmessage (string)、失敗の場合はerror (string) を含む辞書。成功例: {"success": True, "id": "newDocId", "message": "Document added to 'logs'"}失敗例: {"success": False, "error": "Firestore not initialized..."}

Claude (または他の MCP クライアント) と併用する

このMCP Firebaseサーバーは、別プロセスとして実行されるように設計されており、通常はMCPクライアントアプリケーション（Claude Desktopや、MCPサーバーを管理できるWindsurfなどのプラットフォームで構築されたカスタムアプリケーションなど）によって起動されます。クライアントは、通常、ローカルで実行されるサーバーの場合はstdio （標準入出力）を介してこのサーバーと通信します。

一般的な統合手順:

1. サーバーの可用性: MCP クライアントが実行されるシステムまたはプロセスを起動できるシステムで、 mcp_firebase_server.pyとその依存関係 ( serviceAccountKey.jsonを含む) にアクセスできることを確認します。
2. クライアント設定： MCPクライアントアプリケーションは、 MCPFirebaseServerの起動方法を設定する必要があります。この設定では通常、以下の項目を指定します。
   • 実行するコマンド(例: pythonまたはuv run python )。
   • そのコマンドの引数(例: mcp_firebase_server.pyへのパス)。
   • オプションで、サーバーが必要とする可能性のある環境変数(現在のサーバーでは、同じディレクトリにserviceAccountKey.jsonあることを想定していますが、キー パスの環境変数を使用することもできます)。
3. 打ち上げとコミュニケーション:
   • MCP クライアントがこのサーバーが提供するツールを使用する必要がある場合、設定されたコマンドを使用してmcp_firebase_server.pyを起動します。
   • その後、クライアントとサーバーはMCPプロトコル（例： stdio経由）を介して通信します。クライアントは利用可能なツール（ query_firestore_collection 、 add_document_to_firestore ）を検出し、それらを呼び出すことができます。

概念的な構成例 (Claude Desktop のような MCP クライアントの場合):

MCP対応クライアントアプリケーション（MCPドキュメントに記載されているClaude Desktopなど）の多くは、MCPサーバーの起動と管理方法を定義するために構成ファイル（多くの場合JSON形式）を使用します。具体的な形式はクライアントによって異なる場合がありますが、基本的な考え方はほぼ同じです。

以下は、MCPドキュメントに記載されているパターンに基づいた概念的な例です。選択したMCPクライアント（Claude Desktop、Windsurfなど）の特定の設定メカニズムに合わせて調整する必要があります。

構成の重要なポイント:

• "command" : 実行する実行ファイル（例： python ）。システムのPATHに含まれていることを確認するか、Pythonインタープリターへのフルパスを指定してください。
• "args" : 引数のリスト。最初の引数は通常、実行するスクリプトです。クライアントがどこから起動されたかに関係なく、クライアントがmcp_firebase_server.pyを見つけられるように、 mcp_firebase_server.pyへの絶対パスを指定することが重要です。
• "cwd" (現在の作業ディレクトリ) : 場合によっては、サーバー プロセスの作業ディレクトリを指定する必要があることがあります。特に、他のファイルへの相対パスに依存している場合です (ただし、 serviceAccountKey.jsonパスはスクリプト自体に対する相対パスであるため、スクリプト パスが絶対パスであれば通常は堅牢です)。
• "env" : 環境変数を渡します。現在のサーバーでは、 serviceAccountKey.json自身のパスを基準に検索しますが、より柔軟な設定が可能なサーバーでは、資格情報パスやその他の設定を環境変数経由で渡すのが一般的です。

インタラクションフロー（要約）:

1. クライアントがサーバーを起動します: MCP クライアント (上記の構成を使用) はmcp_firebase_server.pyを起動します。
2. **サーバーの初期化:**サーバーは Firebase への接続を試みます。
3. **ツールの検出と呼び出し:**クライアントは必要に応じてquery_firestore_collectionやadd_document_to_firestoreなどのツールを検出して呼び出します。
4. **サーバーの応答:**結果はstdio経由でクライアントに送り返されます。

Claude Desktop または Windsurf の具体的な手順:

• Claude Desktop: Claude Desktop をご利用の場合は、カスタム MCP サーバーの追加と設定方法については、ドキュメントをご覧ください。上記の JSON 構造は、一般的なパターンとして適用できます。
• Windsurf: Windsurf がオーケストレーターとして利用されており、MCP サーバーの管理をサポートしている場合、これらの外部ツールサーバーの定義と起動には独自の方法があります。詳細については Windsurf のドキュメントを参照する必要がありますが、コア情報（コマンド、 mcp_firebase_server.pyを実行するための引数）は同じです。

クライアントに専用の MCP サーバー管理 UI/構成ファイルがなく、シェル コマンドを実行して stdio 経由で対話できる場合は、プログラムでmcp_firebase_server.pyスクリプトを起動し、MCP クライアント ライブラリ ( mcp.client.stdioにあるものなど) を使用して通信します。

開発とテスト

• mcp dev mcp_firebase_server.pyを使用して、MCP Inspector でサーバーを実行します。これにより、検出されたツールを確認し、インタラクティブにテストできます。
• serviceAccountKey.jsonが正しく配置されているか、または MCP クライアントによってサーバーが起動されたときにSERVICE_ACCOUNT_KEY_PATH環境変数が設定されていることを確認します。
• サーバーのコンソール出力で、Firebase 初期化メッセージとランタイム エラーを確認します。

run_server.shスクリプト:

プロジェクト ルートのrun_server.shスクリプトは、次の目的で設計されています。

1. 独自の場所を決定し、現在のディレクトリをそこに変更します。
2. プロジェクト ルートにvenvという名前の Python 仮想環境が存在する場合は、それを見つけてアクティブ化します。
3. pythonインタープリター (アクティブ化された venv から実行するのが理想的) を使用して、 mcp_firebase_server.pyスクリプトを実行します。

このスクリプトは、MCPサーバーが意図した環境で実行されることを保証します。実行可能ファイル（ chmod +x run_server.sh ）を作成してください。