Firestore MCP Server

A Model Context Protocol (MCP) server that provides secure, permission-controlled access to Firebase Firestore. This server allows AI assistants and other MCP clients to interact with Firestore databases through a standardized interface.

Features

Core Functionality

• 🔐 Granular Permissions: Control access at the collection and operation level

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

• 🔍 Advanced Queries: Support for filtering, ordering, and limiting results

• 📁 Subcollection Support: Work with nested collections and documents

• 🔄 Batch Operations: Execute multiple operations atomically

• 💾 Transactions: Ensure data consistency with transactional operations

• 🎯 Field Value Operations: Atomic increments, array operations, and server timestamps

Security & Control

• ✅ Collection-level access control

• 🛡️ Operation-specific permissions (read, write, delete, query)

• 🔒 Default deny with explicit allow rules

• 📋 Conditional permissions (coming soon)

Installation

Using npm/yarn/pnpm

From Source

Configuration

Environment Variables

Create a .env file with your Firestore configuration:

Permission Configuration

Create a permissions.json file to control access:

Usage

Starting the Server

Claude Desktop Integration

Add to your Claude Desktop configuration:

Available Tools

Basic Operations

1. firestore-list-collections

   • List all accessible collections

   {}

2. firestore-get-collection

   • Get all documents from a collection

   { "collectionId": "users" }

3. firestore-get-document

   • Get a specific document

   { "collectionId": "users", "documentId": "user123" }

4. firestore-create-document

   • Create a new document

   { "collectionId": "users", "documentId": "user123", "data": { "name": "John Doe", "email": "john@example.com" } }

5. firestore-update-document

   • Update an existing document

   { "collectionId": "users", "documentId": "user123", "data": { "name": "Jane Doe" } }

6. firestore-delete-document

   • Delete a document

   { "collectionId": "users", "documentId": "user123" }

Query Operations

7. firestore-query-collection

   • Query documents with filters

   { "collectionId": "users", "filters": [ { "field": "age", "operator": ">", "value": 18 } ], "orderBy": { "field": "createdAt", "direction": "desc" }, "limit": 10 }

Subcollection Operations

8. firestore-list-subcollections

   • List subcollections of a document

   { "documentPath": "users/user123" }

9. firestore-get-collection-by-path

   • Get documents from a subcollection

   { "collectionPath": "users/user123/orders" }

10. firestore-create-document-by-path

    • Create a document in a subcollection

    { "collectionPath": "users/user123/orders", "data": { "item": "Widget", "quantity": 2 } }

Batch Operations

11. firestore-batch-write

    • Execute multiple write operations atomically

    { "operations": [ { "type": "create", "collectionPath": "products", "documentId": "product1", "data": { "name": "Widget" } }, { "type": "update", "documentPath": "inventory/product1", "data": { "count": 100 } } ] }

12. firestore-batch-read

    • Read multiple documents in one operation

    { "documentPaths": [ "users/user1", "users/user2", "products/product1" ] }

13. firestore-transaction

    • Execute a transaction with reads and conditional writes

    { "reads": ["products/product1"], "operations": [ { "type": "update", "documentPath": "products/product1", "data": { "stock": 99 } } ], "conditionScript": "return readResults['products/product1'].data.stock > 0;" }

Field Value Operations

14. firestore-increment-field

    • Atomically increment a numeric field

    { "documentPath": "stats/daily", "field": "visitCount", "incrementBy": 1 }

15. firestore-array-union

    • Add elements to an array without duplicates

    { "documentPath": "users/user123", "field": "tags", "elements": ["premium", "verified"] }

16. firestore-server-timestamp

    • Set fields to server timestamp

    { "documentPath": "users/user123", "fields": ["lastLogin", "modifiedAt"] }

Resources

The server also provides MCP resources for direct access to Firestore data:

• firestore://collections - List all collections

• firestore://collection/{collectionId} - Access collection data

• firestore://collection/{collectionId}/document/{documentId} - Access document data

• firestore://path/{path} - Access any path (collections or documents)

Examples

Basic CRUD Operations

Working with Subcollections

Batch Operations

Field Value Operations

Security Best Practices

1. Use Minimal Permissions: Only grant access to collections and operations that are necessary

2. Default Deny: Set defaultAllow: false in production environments

3. Service Account Security: Protect your service account credentials

4. Environment Variables: Never commit credentials to version control

5. Audit Access: Regularly review permission configurations

Development

Running Tests

Building

Docker

Troubleshooting

Common Issues

1. Authentication Errors

   • Ensure GOOGLE_APPLICATION_CREDENTIALS points to a valid service account

   • Check that the service account has necessary Firestore permissions

2. Permission Denied

   • Verify collection is listed in permissions configuration

   • Check that the operation is allowed for the collection

3. Connection Issues

   • Confirm project ID is correct

   • Check network connectivity to Firestore

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

MIT License - see LICENSE for details.

Acknowledgments

Built on the Model Context Protocol by Anthropic.