Firestore MCP Server

Model Context Protocol (MCP) server for Firebase Firestore. This server enables AI assistants like Claude to directly interact with your Firestore database.

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

Features / 機能

• Full CRUD Operations: Create, read, update, and delete documents

• Collection Management: List collections and subcollections

• Query Support: Filter documents with Firestore query operators

• Document Counting: Get document counts without fetching all data

• Type Conversion: Automatic handling of Firestore types (Timestamp, GeoPoint, etc.)

• フルCRUD操作: ドキュメントの作成、読み取り、更新、削除

• コレクション管理: コレクションとサブコレクションの一覧表示

• クエリサポート: Firestoreクエリ演算子によるドキュメントのフィルタリング

• ドキュメントカウント: 全データを取得せずにドキュメント数を取得

• 型変換: Firestoreの型（Timestamp、GeoPointなど）の自動処理

Requirements / 必要条件

• Node.js 18+

• Firebase project with Firestore enabled / Firestoreが有効なFirebaseプロジェクト

• Firebase Admin SDK credentials (service account) / Firebase Admin SDK認証情報（サービスアカウント）

Installation / インストール

1. Clone the repository / リポジトリをクローン

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

3. Configure Firebase credentials / Firebase認証情報を設定

Copy the example environment file: / 環境変数ファイルをコピー:

Edit .env with your Firebase credentials: / .envにFirebase認証情報を設定:

How to get Firebase credentials / Firebase認証情報の取得方法

1. Go to Firebase Console / Firebaseコンソールにアクセス

2. Select your project / プロジェクトを選択

3. Navigate to Project Settings > Service accounts / プロジェクトの設定 > サービスアカウントに移動

4. Click Generate new private key / 新しい秘密鍵を生成をクリック

5. Download the JSON file / JSONファイルをダウンロード

6. Copy values to your .env file: / .envファイルに値をコピー:

   • project_id → FIREBASE_PROJECT_ID

   • client_email → FIREBASE_CLIENT_EMAIL

   • private_key → FIREBASE_PRIVATE_KEY

4. Build the project / プロジェクトをビルド

Claude Code Configuration / Claude Code設定

Project-level configuration (recommended) / プロジェクトレベル設定（推奨）

Create .mcp.json in your project root: / プロジェクトルートに.mcp.jsonを作成:

Note: The server automatically loads .env from its installation directory, so cwd is not required.

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

With environment variables inline / 環境変数をインラインで指定

If you prefer not to use a .env file: / .envファイルを使用しない場合:

After configuration / 設定後

1. Restart Claude Code / Claude Codeを再起動

2. When prompted, approve the MCP server / プロンプトが表示されたらMCPサーバーを承認

3. The Firestore tools will be available in your conversation / Firestoreツールが会話で使用可能になります

Available Tools / 利用可能なツール

Collection Operations / コレクション操作

Document Operations / ドキュメント操作

Query Operations / クエリ操作

Supported Query Operators / サポートされているクエリ演算子

• == - Equal to / 等しい

• != - Not equal to / 等しくない

• < - Less than / より小さい

• <= - Less than or equal to / 以下

• > - Greater than / より大きい

• >= - Greater than or equal to / 以上

• array-contains - Array contains value / 配列に値が含まれる

• in - Value in array / 配列内の値

• array-contains-any - Array contains any of values / 配列にいずれかの値が含まれる

Usage Examples / 使用例

List all collections / 全コレクションを一覧表示

Get a specific document / 特定のドキュメントを取得

List documents with limit / ドキュメントを件数制限付きで一覧表示

Query documents / ドキュメントをクエリ

Create a document / ドキュメントを作成

Update a document / ドキュメントを更新

Delete a document / ドキュメントを削除

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

Configuration Options / 設定オプション

Environment Variables / 環境変数

Adjusting Behavior / 動作の調整

Default query limit / デフォルトのクエリ制限

The default limit for list_documents and query_documents is 20. You can override this per-request by specifying the limit parameter.

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

Merge vs Replace on update / 更新時のマージと置換

By default, update_document merges new data with existing document data (merge: true). Set merge: false to replace the entire document.

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

Security Considerations / セキュリティに関する注意事項

• Never commit - They contain sensitive credentials

• Use service accounts with minimal permissions - Only grant Firestore access needed

• Consider read-only service accounts for development - Prevent accidental data modification

• Rotate credentials regularly - Generate new service account keys periodically

• .env - 機密性の高い認証情報が含まれています

• 最小権限のサービスアカウントを使用 - 必要なFirestoreアクセス権限のみを付与

• 開発には読み取り専用サービスアカウントを検討 - 誤ってデータを変更することを防止

• 認証情報を定期的にローテーション - サービスアカウントキーを定期的に再生成

Creating a read-only service account / 読み取り専用サービスアカウントの作成

1. Go to Google Cloud Console / Google Cloudコンソールにアクセス

2. Navigate to IAM & Admin > Service Accounts / IAMと管理 > サービスアカウントに移動

3. Create a new service account / 新しいサービスアカウントを作成

4. Grant only the Cloud Datastore User role (read-only) / Cloud Datastore ユーザーロール（読み取り専用）のみを付与

5. Generate and download the key / キーを生成してダウンロード

Firestore Data Types / Firestoreデータ型

The server automatically handles these Firestore types:

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

Troubleshooting / トラブルシューティング

"Permission denied" errors / 「権限が拒否されました」エラー

• Verify your service account has Firestore access / サービスアカウントにFirestoreアクセス権があることを確認

• Check that FIREBASE_PROJECT_ID matches your actual project / FIREBASE_PROJECT_IDが実際のプロジェクトと一致していることを確認

• Ensure the private key includes \n characters for newlines / 秘密鍵に改行用の\n文字が含まれていることを確認

"Could not load the default credentials" / 「デフォルトの認証情報を読み込めませんでした」エラー

• Verify all three environment variables are set / 3つの環境変数がすべて設定されていることを確認

• Check that FIREBASE_PRIVATE_KEY is properly quoted / FIREBASE_PRIVATE_KEYが適切に引用符で囲まれていることを確認

MCP server not appearing in Claude / MCPサーバーがClaudeに表示されない

• Restart Claude Code after adding .mcp.json / .mcp.jsonを追加した後、Claude Codeを再起動

• Check the file path in configuration is correct / 設定のファイルパスが正しいことを確認

• Verify the build completed successfully (dist/index.js exists) / ビルドが正常に完了したことを確認（dist/index.jsが存在する）

MCP server shows "failed" status / MCPサーバーが「失敗」ステータスを表示

• The server loads .env from its installation directory automatically / サーバーはインストールディレクトリから自動的に.envを読み込みます

• Verify your .env file exists in the firestore-mcp directory (not your project directory) / .envファイルがfirestore-mcpディレクトリ（プロジェクトディレクトリではなく）に存在することを確認

• Run node /path/to/firestore-mcp/dist/index.js manually to see error messages / エラーメッセージを確認するにはnode /path/to/firestore-mcp/dist/index.jsを手動で実行

Development / 開発

License / ライセンス

MIT

Contributing / コントリビュート

Contributions are welcome! Please open an issue or submit a pull request.

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