# Firestore MCP Server
[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for Firebase Firestore. This server enables AI assistants like Claude to directly interact with your Firestore database.
Firebase Firestore用の[Model Context Protocol (MCP)](https://modelcontextprotocol.io/)サーバーです。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 / リポジトリをクローン
```bash
git clone https://github.com/your-username/firestore-mcp.git
cd firestore-mcp
```
### 2. Install dependencies / 依存関係をインストール
```bash
npm install
```
### 3. Configure Firebase credentials / Firebase認証情報を設定
Copy the example environment file: / 環境変数ファイルをコピー:
```bash
cp .env.example .env
```
Edit `.env` with your Firebase credentials: / `.env`にFirebase認証情報を設定:
```env
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](https://console.firebase.google.com/) / [Firebaseコンソール](https://console.firebase.google.com/)にアクセス
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 / プロジェクトをビルド
```bash
npm run build
```
## Claude Code Configuration / Claude Code設定
### Project-level configuration (recommended) / プロジェクトレベル設定（推奨）
Create `.mcp.json` in your project root: / プロジェクトルートに`.mcp.json`を作成:
```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`ファイルを使用しない場合:
```json
{
"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](https://console.cloud.google.com/) / [Google Cloudコンソール](https://console.cloud.google.com/)にアクセス
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 / 開発
```bash
# 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を作成するか、プルリクエストを送信してください。
