firebase-mcp

GitHub

This repository provides a Model Context Protocol (MCP) server that enables LLM clients to interact with Firebase services like Authentication, Firestore, and Storage. It allows LLMs to access Firebase data and tools.

130

Firebase MCP Server

Overview

This Firebase MCP (Model Context Protocol) server enables LLM clients to interact with Firebase services, including Authentication, Firestore, and Storage. It supports LLM clients like Claude Desktop, Cursor, Roo Code, and Cline. The server exposes Firebase services through MCP tools, handling authentication and connection management.

1. Firebase Configuration

Go to Firebase Console
Navigate to Project Settings > Service Accounts
Click "Generate new private key"
Save the JSON file securely

2. Environment Variables

The server requires the following environment variables:

SERVICE_ACCOUNT_KEY_PATH: Path to your Firebase service account key JSON file (required)
FIREBASE_STORAGE_BUCKET: Bucket name for Firebase Storage (optional)
- If not provided, defaults to [projectId].appspot.com

3. Install MCP Server

Add the server configuration to your MCP settings file:

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
Cursor: [project root]/.cursor/mcp.json
Roo Code (VS Code Extension): (~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json)
Cline (VS Code Extension): ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

MCP Servers can be installed manually or at runtime via npx (recommended). How you install determines your configuration:

Configure for npx

{
  "firebase-mcp": {
    "command": "npx",
    "args": [
      "-y",
      "@gannonh/firebase-mcp"
    ],
    "env": {
      "SERVICE_ACCOUNT_KEY_PATH": "/absolute/path/to/serviceAccountKey.json",
      "FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app"
    }
  }
}

Configure for local installation

{
  "firebase-mcp": {
    "command": "node",
    "args": [
      "/absolute/path/to/firebase-mcp/dist/index.js"
    ],
    "env": {
      "SERVICE_ACCOUNT_KEY_PATH": "/absolute/path/to/serviceAccountKey.json",
      "FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app"
    }
  }
}

Manual Installation

Install Dependencies

git clone https://github.com/gannonh/firebase-mcp
cd firebase-mcp
npm install

Build the Project

npm run build

Test your Installation

To make sure everything is working, simply prompt your client: Please run through and test all of your Firebase MCP tools.

Features

Authentication Tools

auth_get_user: Get user details by ID or email

{
  identifier: string // User ID or email address
}

Firestore Tools

firestore_add_document: Add a document to a collection
```
{
  collection: string,
  data: object
}
```

firestore_list_collections: List available collections

{
  documentPath?: string, // Optional parent document path
  limit?: number,        // Default: 20
  pageToken?: string     // For pagination
}

firestore_list_documents: List documents with optional filtering

{
  collection: string,
  filters?: Array<{
    field: string,
    operator: string,
    value: any
  }>,
  limit?: number,
  pageToken?: string
}

firestore_get_document: Get a specific document
```
{
  collection: string,
  id: string
}
```

firestore_update_document: Update an existing document

{
  collection: string,
  id: string,
  data: object
}

firestore_delete_document: Delete a document
```
{
  collection: string,
  id: string
}
```

Storage Tools

storage_list_files: List files in a directory

{
  directoryPath?: string, // Optional path, defaults to root
  pageSize?: number,      // Number of items per page, defaults to 10
  pageToken?: string      // Token for pagination
}

storage_get_file_info: Get file metadata and download URL
```
{
  filePath: string // Path to the file in storage
}
```

Development

Building

npm run build

Testing

The project uses Jest for testing. Tests can be run against Firebase emulators to avoid affecting production data.

Install Firebase Emulators

npm install -g firebase-tools
firebase init emulators

Start Emulators
```
firebase emulators:start
```
Run Tests
```
npm run test:emulator
```

Architecture

The server is structured into three main components:

src/
⌘⌘⌘ index.ts              # Server entry point
⌘⌘⌘ lib/
    ⌘⌘⌘ firebase/
        ⌘⌘⌘ authClient.ts       # Authentication operations
        ⌘⌘⌘ firebaseConfig.ts   # Firebase configuration
        ⌘⌘⌘ firestoreClient.ts  # Firestore operations
        ⌘⌘⌘ storageClient.ts    # Storage operations

Each client module implements specific Firebase service operations and exposes them as MCP tools.

Contributing

Fork the repository
Create a feature branch
Implement changes with tests
Submit a pull request

License

MIT License - see LICENSE file for details

Related Resources

Troubleshooting

Common Issues

"The specified bucket does not exist" Error

If you encounter this error when trying to access Firebase Storage:

Check that your Firebase project has Storage enabled
- Go to the Firebase Console
- Navigate to Storage
- Complete the initial setup if you haven't already
Verify the correct bucket name
- The default bucket name is usually [projectId].appspot.com
- Some projects use [projectId].firebasestorage.app instead
- You can find your bucket name in the Firebase Console under Storage
Set the FIREBASE_STORAGE_BUCKET environment variable
- Add the correct bucket name to your MCP configuration
- Example: "FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app"

"Firebase is not initialized" Error

If you see this error:

Verify your service account key path
- Make sure the path in SERVICE_ACCOUNT_KEY_PATH is correct and absolute
- Check that the file exists and is readable
Check service account permissions
- Ensure the service account has the necessary permissions for the Firebase services you're using
- For Storage, the service account needs the Storage Admin role

JSON Parsing Errors

If you see errors about invalid JSON:

Make sure there are no console.log statements in the code
- All logging should use console.error to avoid interfering with the JSON communication
- The MCP protocol uses stdout for JSON communication
Check for syntax errors in your requests
- Verify that all parameters are correctly formatted
- Check for typos in field names

Summary

The Firebase MCP Server bridges LLM clients with Firebase services via the Model Context Protocol. It enables LLMs like Claude and Cursor to interact with Firebase Authentication, Firestore, and Storage. Key features include user management, document database operations, and file storage/retrieval, all accessible through MCP tools.

Setup involves configuring Firebase, setting environment variables for the service account key path and storage bucket, and installing the server using either npx or a local installation. The server provides tools for authentication (e.g., auth_get_user), Firestore (e.g., firestore_add_document, firestore_get_document), and Storage (e.g., storage_list_files, storage_get_file_info).

The architecture is structured into modules for authentication, Firestore, and storage operations. Development includes building, testing with Jest and Firebase emulators, and contributing through forking, creating feature branches, and submitting pull requests.

Repository

gannonh

gannonh/firebase-mcp

Created

March 8, 2025

Updated

March 28, 2025

Language

TypeScript