Firebase MCP Server: Setup, Configuration, and Production Guide
Quick Answer
- What it does: The Firebase MCP server lets AI agents (Claude, GPT, etc.) directly query Firestore, manage authentication, run A/B tests, and invoke cloud functions using natural language through the Model Context Protocol.
- First check: Ensure your Firebase project has the Firestore API enabled in Google Cloud Console, and your API key has appropriate permissions. The minimal setup requires a project ID and API key passed as CLI arguments.
- Minimal command:
npx -y @firebase/mcp-server --project your-project-id --api-key your-api-key - Version boundary: Requires Node.js 18+ and a Firebase project with billing enabled for some features (Cloud Functions, larger Firestore operations).
- Critical limitation: Firestore transactions are capped at 500 operations/second; high-concurrency AI agent calls can trigger rate limits and incur significant read/write costs.
What Problem It Solves
Firebase MCP Server bridges the gap between large language models (LLMs) and Firebase services. Without it, an AI agent cannot directly interact with your Firestore database, user authentication system, or cloud functions. With this MCP server, an agent can:
- Query Firestore collections and documents using natural language
- Create, update, or delete user accounts
- Run A/B experiments and retrieve experiment data
- Invoke cloud functions and retrieve results
- Manage Firebase Remote Config and Performance Monitoring data
This eliminates the need for custom API wrappers or middleware when building AI-powered applications that need to read or write Firebase data.
Installation and Quick Start
No installation is required. The Firebase MCP server runs via npx:
JSON{ "mcpServers": { "firebase-mcp": { "command": "npx", "args": [ "-y", "@firebase/mcp-server", "--project", "your-project-id", "--api-key", "your-api-key" ] } } }
Replace your-project-id with your Firebase project ID (found in Project Settings) and your-api-key with a Web API key from the same settings page.
For Cursor users, place this in .cursor/mcp.json. For Claude Desktop, add it to claude_desktop_config.json.
Parameters and Environment Variables
The Firebase MCP server accepts the following CLI arguments:
| Argument | Required | Description |
|---|---|---|
--project | Yes | Firebase project ID |
--api-key | Yes | Web API key from Firebase project settings |
Environment variables that affect behavior:
| Variable | Purpose |
|---|---|
HTTPS_PROXY | Configure an outbound proxy if your network restricts direct HTTPS access to Firebase |
FIREBASE_MCP_DEBUG | Set to true to enable verbose logging for troubleshooting |
Root Cause Analysis
The most common failure point is permission misconfiguration. Firebase Security Rules default to denying all access. When an MCP server attempts to read or write data, it uses the API key for authentication, but the Security Rules still apply.
The second most common issue is API enablement. New Firebase projects often have the Firestore API disabled by default. The MCP server cannot interact with Firestore until you explicitly enable the API in Google Cloud Console.
Network connectivity is the third frequent cause. The MCP server must make outbound HTTPS connections to firestore.googleapis.com and identitytoolkit.googleapis.com. Corporate proxies or restricted VPCs can block these connections.
Common Errors and Fixes
| Error | Root Cause | Fix |
|---|---|---|
PERMISSION_DENIED: Missing or insufficient permissions | Security Rules block the request | Update Firestore rules to allow authenticated access: allow read, write: if request.auth != null; |
Error: 7 PERMISSION_DENIED: Cloud Firestore API has not been used in project before or it is disabled | Firestore API not enabled | Go to Google Cloud Console → API Library → Enable Cloud Firestore API |
Error: 14 UNAVAILABLE: Getting metadata from plugin failed with error: socket hang up | Network connectivity issue | Check outbound HTTPS access; configure HTTPS_PROXY if behind a proxy |
Error: 3 INVALID_ARGUMENT: Invalid collection reference. Collection IDs must match [a-zA-Z0-9_-]+ | Collection name contains invalid characters | Use only letters, digits, underscores, and hyphens in collection names |
Production Notes and Security Checks
Security Rules: Never use allow read, write: if true; in production. Restrict access based on authenticated user roles or service account conditions. For MCP server access, consider using a dedicated service account with Firestore IAM roles instead of a Web API key.
Rate Limits: Firestore has a maximum write rate of 10,000 writes/second per database, but transactions are limited to 500 operations/second. If your AI agent performs many small writes, batch them using the batch: true parameter.
Cost Management: Each Firestore read costs ~$0.06 per 100,000 reads. An AI agent that queries collections frequently can generate unexpected bills. Set budget alerts in Google Cloud Console.
Network Security: Restrict your API key to specific IP ranges or HTTP referrers if your MCP host runs in a known environment. This prevents unauthorized use of your key.
Latency: Firestore queries to regions far from your MCP host add 100-500ms latency. Deploy your Firebase project in the same region as your MCP server for best performance.
FAQ
Q: Does the Firebase MCP server support real-time listeners (onSnapshot)?
A: No. The MCP server provides CRUD operations and query tools only. For real-time updates, implement the Firebase SDK directly in your application and use webhooks or polling to trigger MCP tools when data changes.
Q: How do I securely manage Firebase service account keys in MCP?
A: Use environment variables or your MCP host's secret management (e.g., Cursor's .env file). Never hardcode keys in JSON configuration files. For production, use Google Cloud Secret Manager to store keys and authenticate via a service account with limited IAM roles.
Q: Does the Firebase MCP server support batch writes and transactions?
A: Yes. Pass batch: true or transaction: true parameters in your MCP tool calls. Note the 500 operations/second transaction limit and that transactions cannot contain read operations unless using optimistic locking patterns.