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.

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.)

Requirements

• Node.js 18+

• Firebase project with Firestore enabled

• Firebase Admin SDK credentials (service account)

Installation

1. Clone the repository

2. Install dependencies

3. Configure Firebase credentials

Copy the example environment file:

Edit .env with your Firebase credentials:

How to get Firebase credentials

1. Go to Firebase Console

2. Select your project

3. Navigate to Project Settings > Service accounts

4. Click Generate new private key

5. Download the JSON file

6. Copy values to your .env file:

   • project_id → FIREBASE_PROJECT_ID

   • client_email → FIREBASE_CLIENT_EMAIL

   • private_key → FIREBASE_PRIVATE_KEY

4. Build the project

Claude Code Configuration

Project-level configuration (recommended)

Create .mcp.json in your project root:

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

With environment variables inline

If you prefer not to use a .env file:

After configuration

1. Restart Claude Code

2. When prompted, approve the MCP server

3. The Firestore tools will be available in your conversation

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.

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.

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

Creating a read-only service account

1. Go to Google Cloud Console

2. Navigate to IAM & Admin > Service Accounts

3. Create a new service account

4. Grant only the Cloud Datastore User role (read-only)

5. Generate and download the key

Firestore Data Types

The server automatically handles these Firestore types:

Troubleshooting

"Permission denied" errors

• Verify your service account has Firestore access

• Check that FIREBASE_PROJECT_ID matches your actual project

• Ensure the private key includes \n characters for newlines

"Could not load the default credentials"

• Verify all three environment variables are set

• Check that FIREBASE_PRIVATE_KEY is properly quoted

MCP server not appearing in Claude

• Restart Claude Code after adding .mcp.json

• Check the file path in configuration is correct

• Verify the build completed successfully (dist/index.js exists)

MCP server shows "failed" status

• The server loads .env from its installation directory automatically

• Verify your .env file exists in the firestore-mcp directory (not your project directory)

• Run node /path/to/firestore-mcp/dist/index.js manually to see error messages

Development

License

MIT

Contributing

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