Firestore MCP

🚀 Firestore MCP Server

Firebase Firestore用のModel Context Protocol (MCP)サーバーです。ClaudeなどのAIアシスタントがFirestoreデータベースと直接やり取りできるようになります。

🚀 クイックスタート

このサーバーを使用することで、ClaudeなどのAIアシスタントがFirestoreデータベースと直接やり取りできるようになります。以下の手順に従ってサーバーをセットアップしてください。

✨ 主な機能

• フルCRUD操作: ドキュメントの作成、読み取り、更新、削除
• コレクション管理: コレクションとサブコレクションの一覧表示
• クエリサポート: Firestoreクエリ演算子によるドキュメントのフィルタリング
• ドキュメントカウント: 全データを取得せずにドキュメント数を取得
• 型変換: Firestoreの型（Timestamp、GeoPointなど）の自動処理

📦 インストール

1. リポジトリをクローン

git clone https://github.com/your-username/firestore-mcp.git
cd firestore-mcp

2. 依存関係をインストール

npm install

3. Firebase認証情報を設定

環境変数ファイルをコピー:

cp .env.example .env

.envにFirebase認証情報を設定:

FIREBASE_PROJECT_ID=your-project-id
FIREBASE_CLIENT_EMAIL=firebase-adminsdk-xxxxx@your-project.iam.gserviceaccount.com
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"

Firebase認証情報の取得方法

1. Firebaseコンソールにアクセス
2. プロジェクトを選択
3. プロジェクトの設定 > サービスアカウントに移動
4. 新しい秘密鍵を生成をクリック
5. JSONファイルをダウンロード
6. .envファイルに値をコピー:
   • project_id → FIREBASE_PROJECT_ID
   • client_email → FIREBASE_CLIENT_EMAIL
   • private_key → FIREBASE_PRIVATE_KEY

4. プロジェクトをビルド

npm run build

💻 使用例

基本的な使用法

全コレクションを一覧表示

Tool: list_collections

特定のドキュメントを取得

Tool: get_document
Parameters:
  documentPath: "users/user123"

ドキュメントを件数制限付きで一覧表示

Tool: list_documents
Parameters:
  collectionPath: "users"
  limit: 10

高度な使用法

ドキュメントをクエリ

Tool: query_documents
Parameters:
  collectionPath: "users"
  field: "status"
  operator: "=="
  value: "active"
  limit: 20

ドキュメントを作成

Tool: create_document
Parameters:
  collectionPath: "users"
  data: {"name": "John Doe", "email": "john@example.com", "createdAt": "2024-01-01T00:00:00Z"}
  documentId: "user123"  # optional, auto-generated if not provided

ドキュメントを更新

Tool: update_document
Parameters:
  documentPath: "users/user123"
  data: {"name": "Jane Doe"}
  merge: true  # true = merge with existing, false = replace entirely

ドキュメントを削除

Tool: delete_document
Parameters:
  documentPath: "users/user123"

サブコレクションにアクセス

Tool: list_documents
Parameters:
  collectionPath: "users/user123/orders"
  limit: 10

📚 ドキュメント

利用可能なツール

コレクション操作

ドキュメント操作

クエリ操作

サポートされているクエリ演算子

• == - 等しい
• != - 等しくない
• < - より小さい
• <= - 以下
• > - より大きい
• >= - 以上
• array-contains - 配列に値が含まれる
• in - 配列内の値
• array-contains-any - 配列にいずれかの値が含まれる

設定オプション

環境変数

動作の調整

デフォルトのクエリ制限

list_documentsとquery_documentsのデフォルト制限は20件です。limitパラメータを指定することでリクエストごとに上書きできます。

更新時のマージと置換

デフォルトでは、update_documentは新しいデータを既存のドキュメントデータにマージします（merge: true）。ドキュメント全体を置き換えるにはmerge: falseを設定します。

Claude Code設定

プロジェクトレベル設定（推奨）

プロジェクトルートに.mcp.jsonを作成:

{
  "mcpServers": {
    "firestore": {
      "command": "node",
      "args": ["/path/to/firestore-mcp/dist/index.js"]
    }
  }
}

注意: サーバーはインストールディレクトリから自動的に.envを読み込むため、cwdは不要です。

環境変数をインラインで指定

.envファイルを使用しない場合:

{
  "mcpServers": {
    "firestore": {
      "command": "node",
      "args": ["/path/to/firestore-mcp/dist/index.js"],
      "env": {
        "FIREBASE_PROJECT_ID": "your-project-id",
        "FIREBASE_CLIENT_EMAIL": "your-client-email",
        "FIREBASE_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n"
      }
    }
  }
}

設定後

1. Claude Codeを再起動
2. プロンプトが表示されたらMCPサーバーを承認
3. Firestoreツールが会話で使用可能になります

🔧 技術詳細

Firestoreデータ型

サーバーは以下のFirestoreデータ型を自動的に処理します：

📄 ライセンス

MIT

⚠️ 重要提示

• .envファイルをコミットしない - 機密性の高い認証情報が含まれています
• 最小権限のサービスアカウントを使用 - 必要なFirestoreアクセス権限のみを付与
• 開発には読み取り専用サービスアカウントを検討 - 誤ってデータを変更することを防止
• 認証情報を定期的にローテーション - サービスアカウントキーを定期的に再生成

💡 使用建议

• 読み取り専用サービスアカウントを作成するには、Google Cloudコンソールにアクセスし、IAMと管理 > サービスアカウントに移動して、新しいサービスアカウントを作成し、Cloud Datastore ユーザーロール（読み取り専用）のみを付与し、キーを生成してダウンロードしてください。
• トラブルシューティングについては、以下のエラーに対応する解決策を参考にしてください。
  • 「権限が拒否されました」エラー: サービスアカウントにFirestoreアクセス権があることを確認し、FIREBASE_PROJECT_IDが実際のプロジェクトと一致していることを確認し、秘密鍵に改行用の\n文字が含まれていることを確認してください。
  • 「デフォルトの認証情報を読み込めませんでした」エラー: 3つの環境変数がすべて設定されていることを確認し、FIREBASE_PRIVATE_KEYが適切に引用符で囲まれていることを確認してください。
  • MCPサーバーがClaudeに表示されない: .mcp.jsonを追加した後、Claude Codeを再起動し、設定のファイルパスが正しいことを確認し、ビルドが正常に完了したことを確認（dist/index.jsが存在する）してください。
  • MCPサーバーが「失敗」ステータスを表示: サーバーはインストールディレクトリから自動的に.envを読み込みます。.envファイルがfirestore-mcpディレクトリ（プロジェクトディレクトリではなく）に存在することを確認し、エラーメッセージを確認するにはnode /path/to/firestore-mcp/dist/index.jsを手動で実行してください。

開発

# 依存関係をインストール
npm install

# ビルド
npm run build

# ウォッチモード（変更時に再ビルド）
npm run dev

コントリビュート

コントリビューションを歓迎します！Issueを作成するか、プルリクエストを送信してください。