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 / リポジトリをクローン

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

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

npm install

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

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

cp .env.example .env

Edit .env with your Firebase credentials: / .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"

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 / プロジェクトをビルド

npm run build

Claude Code Configuration / Claude Code設定

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

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

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

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ファイルを使用しない場合:

{
  "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"
      }
    }
  }
}

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 / コレクション操作

Tool	Description	Parameters
list_collections	List all top-level collections / トップレベルコレクションを一覧表示	None
list_subcollections	List subcollections of a document / ドキュメントのサブコレクションを一覧表示	documentPath
count_documents	Count documents in a collection / コレクション内のドキュメント数をカウント	collectionPath

Document Operations / ドキュメント操作

Tool	Description	Parameters
get_document	Get a single document / 単一ドキュメントを取得	documentPath
list_documents	List documents in a collection / コレクション内のドキュメントを一覧表示	collectionPath, limit?
create_document	Create a new document / 新しいドキュメントを作成	collectionPath, data, documentId?
update_document	Update an existing document / 既存ドキュメントを更新	documentPath, data, merge?
delete_document	Delete a document / ドキュメントを削除	documentPath

Query Operations / クエリ操作

Tool	Description	Parameters
query_documents	Query with filters / フィルタ付きクエリ	collectionPath, field, operator, value, limit?

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 / 全コレクションを一覧表示

Tool: list_collections

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Configuration Options / 設定オプション

Environment Variables / 環境変数

Variable	Required	Description
FIREBASE_PROJECT_ID	Yes	Your Firebase project ID / FirebaseプロジェクトID
FIREBASE_CLIENT_EMAIL	Yes	Service account email / サービスアカウントのメールアドレス
FIREBASE_PRIVATE_KEY	Yes	Service account private key / サービスアカウントの秘密鍵

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 .env files - 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データ型を自動的に処理します：

Firestore Type	JSON Output
Timestamp	ISO 8601 string ("2024-01-01T00:00:00.000Z") / ISO 8601形式の文字列
GeoPoint	{"latitude": 35.6762, "longitude": 139.6503}
DocumentReference	Document path string ("users/user123") / ドキュメントパス文字列
Array	JSON array / JSON配列
Map	JSON object / JSONオブジェクト

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 / 開発

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

# Build / ビルド
npm run build

# Watch mode (rebuild on changes) / ウォッチモード（変更時に再ビルド）
npm run dev

License / ライセンス

MIT

Contributing / コントリビュート

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

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