Firebase MCP

Firebase MCP

概要

Firebase MCP を使用すると、AI アシスタントが次のような Firebase サービスを直接操作できます。

• Firestore：ドキュメントデータベースの操作
• Storage：堅牢なアップロード機能を備えたファイル管理
• Authentication：ユーザー管理と検証

このサーバーは、Claude Desktop、Augment Code、VS Code、Cursor などの MCP クライアントアプリケーションで動作します。

⚠️ 既知の問題：firestore_list_collections ツールは、クライアントのログに Zod 検証エラーを返す場合があります。調査の結果、レスポンスにブール値が含まれていないことが確認されており、これは MCP SDK における誤った検証エラーです。このエラーメッセージが表示されても、クエリは正常に動作し、正しいコレクションデータを返します。これはログレベルのエラーであり、機能には影響しません。

⚡ クイックスタート

前提条件

• サービスアカウントの認証情報を含む Firebase プロジェクト
• Node.js 環境

1. MCP サーバーをインストールする

MCP の設定ファイルにサーバー設定を追加します。

• Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json
• Augment：~/Library/Application Support/Code/User/settings.json
• Cursor：[project root]/.cursor/mcp.json

MCP サーバーは手動でインストールするか、npx を使用して実行時にインストールできます（推奨）。インストール方法によって設定が異なります。

npx 用に設定する（推奨）

{
  "firebase-mcp": {
    "command": "npx",
    "args": [
      "-y",
      "@gannonh/firebase-mcp"
    ],
    "env": {
      "SERVICE_ACCOUNT_KEY_PATH": "/absolute/path/to/serviceAccountKey.json",
      "FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app"
    }
  }
}

ローカルインストール用に設定する

{
  "firebase-mcp": {
    "command": "node",
    "args": [
      "/absolute/path/to/firebase-mcp/dist/index.js"
    ],
    "env": {
      "SERVICE_ACCOUNT_KEY_PATH": "/absolute/path/to/serviceAccountKey.json",
      "FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app"
    }
  }
}

2. インストールをテストする

AI クライアントに「Firebase MCP のすべてのツールをテストしてください」と尋ねます。

🛠️ セットアップと設定

1. Firebase の設定

1. Firebase Console →「プロジェクトの設定」→「サービス アカウント」に移動します
2. 「新しい秘密鍵を生成」をクリックします
3. JSON ファイルを安全に保存します

2. 環境変数

必須

• SERVICE_ACCOUNT_KEY_PATH：Firebase サービスアカウントのキー JSON ファイルへのパス（必須）

任意

• FIREBASE_STORAGE_BUCKET：Firebase Storage のバケット名（デフォルトは [projectId].appspot.com）
• MCP_TRANSPORT：使用するトランスポートタイプ（stdio または http）（デフォルトは stdio）
• MCP_HTTP_PORT：HTTP トランスポートのポート（デフォルトは 3000）
• MCP_HTTP_HOST：HTTP トランスポートのホスト（デフォルトは localhost）
• MCP_HTTP_PATH：HTTP トランスポートのパス（デフォルトは /mcp）
• DEBUG_LOG_FILE：ファイルへのログ記録を有効にします：
  • true に設定すると、~/.firebase-mcp/debug.log に記録します
  • ファイルパスを指定すると、任意の場所に記録します

3. クライアントとの連携

Claude Desktop

編集するファイル：~/Library/Application Support/Claude/claude_desktop_config.json

VS Code / Augment

編集するファイル：~/Library/Application Support/Code/User/settings.json

Cursor

編集するファイル：[project root]/.cursor/mcp.json

📚 API リファレンス

Firestore ツール

ツール	説明	必須パラメーター
firestore_add_document	コレクションにドキュメントを追加	collection、data
firestore_list_documents	フィルタリングしてドキュメントを一覧表示	collection
firestore_get_document	特定のドキュメントを取得	collection、id
firestore_update_document	既存のドキュメントを更新	collection、id、data
firestore_delete_document	ドキュメントを削除	collection、id
firestore_list_collections	ルートコレクションを一覧表示	なし
firestore_query_collection_group	サブコレクションを横断してクエリ	collectionId

Storage ツール

ツール	説明	必須パラメーター
storage_list_files	ディレクトリ内のファイルを一覧表示	なし（オプション：directoryPath）
storage_get_file_info	ファイルのメタデータと URL を取得	filePath
storage_upload	コンテンツからファイルをアップロード	filePath、content
storage_upload_from_url	URL からファイルをアップロード	filePath、url

Authentication ツール

ツール	説明	必須パラメーター
auth_get_user	ID またはメールアドレスでユーザーを取得	identifier

💻 開発者ガイド

インストールとビルド

git clone https://github.com/gannonh/firebase-mcp
cd firebase-mcp
npm install
npm run build

テストの実行

まず、Firebase エミュレーターをインストールして起動します：

npm install -g firebase-tools
firebase init emulators
firebase emulators:start

次に、テストを実行します：

# Run tests with emulator
npm run test:emulator

# Run tests with coverage
npm run test:coverage:emulator

プロジェクト構成

src/
├── index.ts                  # Server entry point
├── utils/                    # Utility functions
└── lib/
    └── firebase/              # Firebase service clients
        ├── authClient.ts     # Authentication operations
        ├── firebaseConfig.ts   # Firebase configuration
        ├── firestoreClient.ts # Firestore operations
        └── storageClient.ts  # Storage operations

🌐 HTTP トランスポート

Firebase MCP は、デフォルトの stdio トランスポートに加えて、HTTP トランスポートにも対応しました。これにより、複数のクライアントからアクセスできるスタンドアロンの HTTP サービスとしてサーバーを実行できます。

HTTP トランスポートでの実行

HTTP トランスポートでサーバーを実行するには：

# Using environment variables
MCP_TRANSPORT=http MCP_HTTP_PORT=3000 node dist/index.js

# Or with npx
MCP_TRANSPORT=http MCP_HTTP_PORT=3000 npx @gannonh/firebase-mcp

HTTP 用のクライアント設定

HTTP トランスポートを使用する場合は、HTTP エンドポイントに接続するよう MCP クライアントを設定します：

{
  "firebase-mcp": {
    "url": "http://localhost:3000/mcp"
  }
}

セッション管理

HTTP トランスポートはセッション管理に対応しているため、複数のクライアントが同じサーバーインスタンスに接続できます。各クライアントには固有のセッション ID が割り当てられ、リクエスト間の状態維持に使用されます。

🔍 トラブルシューティング

よくある問題

Storage バケットが見つからない

「The specified bucket does not exist」というエラーが表示される場合：

1. Firebase Console → Storage でバケット名を確認します
2. FIREBASE_STORAGE_BUCKET 環境変数に正しいバケット名を設定します

Firebase の初期化に失敗する

「Firebase is not initialized」というエラーが表示される場合：

1. サービスアカウントキーのパスが正しく、絶対パスであることを確認します
2. サービスアカウントに Firebase サービスへの適切な権限があることを確認します

複合インデックスが必要

「This query requires a composite index」というエラーが表示される場合：

1. エラーメッセージに記載された URL を確認します
2. リンクを開き、Firebase Console で必要なインデックスを作成します
3. インデックスの作成後（数分かかる場合があります）にクエリを再実行します

firestore_list_collections の Zod 検証エラー

firestore_list_collections ツールの使用時に、「Expected object, received boolean」というメッセージが表示される Zod 検証エラーが発生する場合：

⚠️ 既知の問題：firestore_list_collections ツールは、クライアントログに Zod 検証エラーを返すことがあります。調査の結果、レスポンスにブール値が含まれていないことが確認されているため、これは MCP SDK の誤った検証エラーです。エラーメッセージが表示されても、クエリは正しく動作し、適切なコレクションデータを返します。これはログレベルのエラーであり、機能には影響しません。

デバッグ

ファイルロギングを有効にする

問題の診断に役立てるため、ファイルロギングを有効にできます。

# Log to default location (~/.firebase-mcp/debug.log)
DEBUG_LOG_FILE=true npx @gannonh/firebase-mcp

# Log to a custom location
DEBUG_LOG_FILE=/path/to/custom/debug.log npx @gannonh/firebase-mcp

MCP クライアントの設定でロギングを有効にすることもできます。

{
  "firebase-mcp": {
    "command": "npx",
    "args": ["-y", "@gannonh/firebase-mcp"],
    "env": {
      "SERVICE_ACCOUNT_KEY_PATH": "/path/to/serviceAccountKey.json",
      "FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app",
      "DEBUG_LOG_FILE": "true"
    }
  }
}

ログをリアルタイムで表示する

ログをリアルタイムで表示するには、次のようにします。

# Using tail to follow the log file
tail -f ~/.firebase-mcp/debug.log

# Using a split terminal to capture stderr
npm start 2>&1 | tee logs.txt

MCP Inspector を使用する

MCP Inspector では、対話形式でデバッグできます。

# Install MCP Inspector
npm install -g @mcp/inspector

# Connect to your MCP server
mcp-inspector --connect stdio --command "node ./dist/index.js"

📋 レスポンスのフォーマット

ストレージへのアップロードに対するレスポンスの例

{
  "name": "reports/quarterly.pdf",
  "size": "1024000",
  "contentType": "application/pdf",
  "updated": "2025-04-11T15:37:10.290Z",
  "downloadUrl": "https://storage.googleapis.com/bucket/reports/quarterly.pdf?alt=media",
  "bucket": "your-project.appspot.com"
}

ユーザーには次のように表示されます。

## File Successfully Uploaded! 📁

Your file has been uploaded to Firebase Storage:

**File Details:**
- **Name:** reports/quarterly.pdf
- **Size:** 1024000 bytes
- **Type:** application/pdf
- **Last Updated:** April 11, 2025 at 15:37:10 UTC

**[Click here to download your file](https://storage.googleapis.com/bucket/reports/quarterly.pdf?alt=media)**

🤝 貢献

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. テストを追加して変更を実装します（カバレッジ 80% 以上が必要です）
4. プルリクエストを送信します

📄 ライセンス

MIT ライセンスの詳細については、LICENSE ファイルをご覧ください。

🔗 関連リソース

• Model Context Protocol のドキュメント
• Firebase のドキュメント
• Firebase Admin SDK