README - firestore-mcp by devlimelabs

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

npm install mcp-firestore
# or
yarn add mcp-firestore
# or
pnpm add mcp-firestore

From Source

git clone https://github.com/yourusername/mcp-firestore.git
cd mcp-firestore
pnpm install
pnpm build

Configuration

Environment Variables

Create a .env file with your Firestore configuration:

# Required
FIRESTORE_PROJECT_ID=your-project-id

# Optional - for authentication
GOOGLE_APPLICATION_CREDENTIALS=path/to/service-account.json

Permission Configuration

Create a permissions.json file to control access:

{
  "collections": [
    {
      "collectionId": "users",
      "operations": ["read", "write", "query"]
    },
    {
      "collectionId": "posts",
      "operations": ["read", "query"]
    }
  ],
  "defaultAllow": false
}

Usage

Starting the Server

# With default permissions
mcp-firestore

# With custom permissions file
mcp-firestore --config permissions.json

# With full access (development only)
mcp-firestore --full-access

# With read-only access to specific collections
mcp-firestore --read-only --collections users,posts

Claude Desktop Integration

Add to your Claude Desktop configuration:

{
  "servers": {
    "firestore": {
      "command": "mcp-firestore",
      "args": ["--config", "path/to/permissions.json"],
      "env": {
        "FIRESTORE_PROJECT_ID": "your-project-id"
      }
    }
  }
}

Available Tools

Basic Operations

firestore-list-collections
- List all accessible collections
```
{}
```
firestore-get-collection
- Get all documents from a collection
```
{
  "collectionId": "users"
}
```

firestore-get-document

Get a specific document

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

firestore-create-document

Create a new document

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

firestore-update-document

Update an existing document

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

firestore-delete-document

Delete a document

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

Query Operations

firestore-query-collection

Query documents with filters

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

Subcollection Operations

firestore-list-subcollections
- List subcollections of a document
```
{
  "documentPath": "users/user123"
}
```
firestore-get-collection-by-path
- Get documents from a subcollection
```
{
  "collectionPath": "users/user123/orders"
}
```

firestore-create-document-by-path

Create a document in a subcollection

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

Batch Operations

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 }
    }
  ]
}

firestore-batch-read

Read multiple documents in one operation

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

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

firestore-increment-field

Atomically increment a numeric field

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

firestore-array-union

Add elements to an array without duplicates

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

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

// Create a new user
await client.callTool("firestore-create-document", {
  collectionId: "users",
  documentId: "user123",
  data: {
    name: "John Doe",
    email: "john@example.com",
    createdAt: new Date().toISOString()
  }
});

// Update user data
await client.callTool("firestore-update-document", {
  collectionId: "users",
  documentId: "user123",
  data: {
    lastLogin: new Date().toISOString()
  }
});

// Query active users
await client.callTool("firestore-query-collection", {
  collectionId: "users",
  filters: [
    { field: "status", operator: "==", value: "active" }
  ],
  orderBy: { field: "createdAt", direction: "desc" },
  limit: 10
});

Working with Subcollections

// Create an order for a user
await client.callTool("firestore-create-document-by-path", {
  collectionPath: "users/user123/orders",
  data: {
    items: ["widget1", "widget2"],
    total: 99.99,
    status: "pending"
  }
});

// Get all orders for a user
await client.callTool("firestore-get-collection-by-path", {
  collectionPath: "users/user123/orders"
});

Batch Operations

// Atomic updates across multiple documents
await client.callTool("firestore-batch-write", {
  operations: [
    {
      type: "update",
      documentPath: "products/widget1",
      data: { stock: 95 }
    },
    {
      type: "create",
      collectionPath: "orders",
      data: {
        product: "widget1",
        quantity: 5,
        userId: "user123"
      }
    },
    {
      type: "update",
      documentPath: "users/user123",
      data: { orderCount: 1 }
    }
  ]
});

Field Value Operations

// Increment a counter
await client.callTool("firestore-increment-field", {
  documentPath: "stats/global",
  field: "totalOrders",
  incrementBy: 1
});

// Add tags without duplicates
await client.callTool("firestore-array-union", {
  documentPath: "products/widget1",
  field: "tags",
  elements: ["bestseller", "featured"]
});

// Set server timestamp
await client.callTool("firestore-server-timestamp", {
  documentPath: "logs/access",
  fields: ["timestamp", "lastModified"]
});

Security Best Practices

Use Minimal Permissions: Only grant access to collections and operations that are necessary
Default Deny: Set defaultAllow: false in production environments
Service Account Security: Protect your service account credentials
Environment Variables: Never commit credentials to version control
Audit Access: Regularly review permission configurations

Development

Running Tests

pnpm test
pnpm test:coverage

Building

pnpm build

Docker

# Build image
docker build -t mcp-firestore .

# Run container
docker run -e FIRESTORE_PROJECT_ID=your-project mcp-firestore

Troubleshooting

Common Issues

Authentication Errors
- Ensure GOOGLE_APPLICATION_CREDENTIALS points to a valid service account
- Check that the service account has necessary Firestore permissions
Permission Denied
- Verify collection is listed in permissions configuration
- Check that the operation is allowed for the collection
Connection Issues
- Confirm project ID is correct
- Check network connectivity to Firestore

Contributing

Contributions are welcome! Please read our for details.

License

MIT License - see for details.

Acknowledgments

Built on the Model Context Protocol by Anthropic.