https://github.com/gannonh/firebase-mcp
Model Context Protocol (MCP) server to interact with Firebase services.
https://github.com/gannonh/firebase-mcp
Last synced: 25 days ago
JSON representation
Model Context Protocol (MCP) server to interact with Firebase services.
- Host: GitHub
- URL: https://github.com/gannonh/firebase-mcp
- Owner: gannonh
- License: mit
- Created: 2025-03-08T21:00:09.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2025-03-19T18:58:48.000Z (28 days ago)
- Last Synced: 2025-03-19T19:39:35.502Z (28 days ago)
- Language: TypeScript
- Homepage:
- Size: 289 KB
- Stars: 11
- Watchers: 2
- Forks: 8
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-list - @gannonh/firebase-mcp - mcp?style=social)](https://github.com/gannonh/firebase-mcp): Provides access to Firebase services like Auth, Firestore, and Storage. (Uncategorized / Uncategorized)
- awesome-mcp-servers - @gannonh/firebase-mcp - Firebase services including Auth, Firestore and Storage. (Legend / 🗄️ <a name="databases"></a>Databases)
- awesome-mcp-servers - @gannonh/firebase-mcp - Firebase services including Auth, Firestore and Storage. (Legend / 🗄️ <a name="databases"></a>Databases)
- awesome-mcp-servers - Firebase MCP - Model Context Protocol (MCP) server to interact with Firebase services. (Table of Contents / AI Services)
- awesome-mcp-servers - Firebase MCP - Model Context Protocol (MCP) server to interact with Firebase services. (Table of Contents / AI Services)
README
# Firebase MCP Server
[](https://github.com/gannonh/firebase-mcp/actions/workflows/firebase-tests.yml)
## Overview
The [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol) is an open protocol that enables LLM client applications to use tools and access external data sources. This MCP server allows any LLM client that supports the MCP protocol to interact with Firebase services including:
- **Authentication**: User management and verification
- **Firestore**: Document database operations
- **Storage**: File storage and retrieval
The server exposes Firebase services through MCP tools, making them accessible to LLM clients including [Claude Desktop](https://claude.ai/download), [Cursor](https://www.cursor.com/), [Roo Code](https://github.com/RooVetGit/Roo-Code), and [Cline](https://cline.bot/), while handling authentication and connection management.
## Setup
> The easiest way to install the Firebase MCP server is to simply feed your LLM client (like Cline) the [llms-install.md](./llms-install.md) file.
### 1. Firebase Configuration
- Go to [Firebase Console](https://console.firebase.google.com)
- 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
```json
{
"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
```json
{
"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
```bash
git clone https://github.com/gannonh/firebase-mcp
cd firebase-mcp
npm install
```
##### Build the Project
```bash
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
```typescript
{
identifier: string // User ID or email address
}
```
### Firestore Tools
- `firestore_add_document`: Add a document to a collection
```typescript
{
collection: string,
data: object
}
```
- `firestore_list_collections`: List available collections
```typescript
{
documentPath?: string, // Optional parent document path
limit?: number, // Default: 20
pageToken?: string // For pagination
}
```
- `firestore_list_documents`: List documents with optional filtering
```typescript
{
collection: string,
filters?: Array<{
field: string,
operator: string,
value: any
}>,
limit?: number,
pageToken?: string
}
```
- `firestore_get_document`: Get a specific document
```typescript
{
collection: string,
id: string
}
```
- `firestore_update_document`: Update an existing document
```typescript
{
collection: string,
id: string,
data: object
}
```
- `firestore_delete_document`: Delete a document
```typescript
{
collection: string,
id: string
}
```
### Storage Tools
- `storage_list_files`: List files in a directory
```typescript
{
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
```typescript
{
filePath: string // Path to the file in storage
}
```
## Development
### Building
```bash
npm run build
```
### Testing
The project uses Jest for testing. Tests can be run against Firebase emulators to avoid affecting production data.
1. **Install Firebase Emulators**
```bash
npm install -g firebase-tools
firebase init emulators
```
2. **Start Emulators**
```bash
firebase emulators:start
```
3. **Run Tests**
```bash
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
1. Fork the repository
2. Create a feature branch
3. Implement changes with tests
4. Submit a pull request
## License
MIT License - see [LICENSE](LICENSE) file for details
## Related Resources
- [Model Context Protocol](https://github.com/modelcontextprotocol)
- [Firebase Documentation](https://firebase.google.com/docs)
- [Firebase Admin SDK](https://firebase.google.com/docs/admin/setup)
## Troubleshooting
### Common Issues
#### "The specified bucket does not exist" Error
If you encounter this error when trying to access Firebase Storage:
1. 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
2. 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
3. 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:
1. 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
2. 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:
1. 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
2. Check for syntax errors in your requests
- Verify that all parameters are correctly formatted
- Check for typos in field names