🔥 Firebase MCP Server

A command-based (stdio) Model Context Protocol server for Google Firebase, providing Auth, Firestore, and Storage tools. Credentials are loaded dynamically from your project directory.

Features

• 🔐 Auth Tools — List, get, create, update, delete users & set custom claims
• 📄 Firestore Tools — Browse collections, read/write/query/delete documents
• 📦 Storage Tools — List, upload, download, copy, move & delete files, generate signed URLs
• 🔍 Dynamic Credentials — Automatically finds .firebase/service-account.json walking up from cwd
• 📦 npx-ready — Run directly with npx firebase-mcp-server, no global install needed

Quick Start

1. Get your Service Account Key

1. Go to Firebase Console
2. Select your project
3. Project Settings → Service Accounts → Generate New Private Key
4. Save the downloaded JSON file

2. Place it in your project

# In your project root
mkdir -p .firebase
mv ~/Downloads/your-project-firebase-adminsdk-*.json .firebase/service-account.json

# IMPORTANT: Add to .gitignore!
echo ".firebase/" >> .gitignore

3. Configure your MCP Client

Claude Code (CLI) ⭐ Recommended

Claude Code sets cwd to your project root automatically — credentials are found with zero config:

claude mcp add firebase -- npx -y firebase-mcp-server

That's it. As long as .firebase/service-account.json exists in your project, it works.

Claude Desktop

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "firebase": {
      "command": "npx",
      "args": ["-y", "firebase-mcp-server"]
    }
  }
}

Or pass the credentials path explicitly:

{
  "mcpServers": {
    "firebase": {
      "command": "npx",
      "args": ["-y", "firebase-mcp-server", "--service-account", "/path/to/your-project/.firebase/service-account.json"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "firebase": {
      "command": "npx",
      "args": ["-y", "firebase-mcp-server"]
    }
  }
}

Windsurf

Add to ~/.windsurf/mcp.json:

{
  "mcpServers": {
    "firebase": {
      "command": "npx",
      "args": ["-y", "firebase-mcp-server"]
    }
  }
}

CLI Options

firebase-mcp [options]

Options:
  --service-account <path>   Explicit path to service account JSON file
  --project-dir <path>       Directory to search .firebase/service-account.json from
  --max-output-size <chars>  Max inline output size before results spill to a temp file
  --help                     Show help

Credential Resolution

The server searches for credentials in this order:

1. --service-account <path> — Explicit path to the JSON key file
2. .firebase/service-account.json — Walked up from --project-dir or cwd (like .git lookup)
3. GOOGLE_APPLICATION_CREDENTIALS — Standard Google Cloud env var
4. FIREBASE_SERVICE_ACCOUNT_PATH — Custom env var for explicit path

How does this work with Claude Code?

Claude Code always starts MCP servers with cwd set to your project root. So if your project looks like this:

my-project/
├── .firebase/
│   └── service-account.json   ← found automatically!
├── src/
├── package.json
└── ...

…the server finds credentials without any extra config. No cwd override needed.

For Claude Desktop, cwd is static in the config. Use --service-account for a fixed path, or set cwd in the JSON config.

Local Development & Testing

# Clone and build
git clone <this-repo>
cd firebase-mcp
npm install && npm run build

# Link globally for local testing
npm link

# Test CLI
firebase-mcp --help
firebase-mcp --service-account /path/to/key.json    # explicit
firebase-mcp --project-dir /path/to/your/project     # search from dir
firebase-mcp                                          # search from cwd

# Test with Claude Code (from your Firebase project dir)
cd /path/to/your-project
claude mcp add firebase -- firebase-mcp

# Or test with MCP Inspector
npx @modelcontextprotocol/inspector firebase-mcp

Available Tools

🔐 Auth Tools

Tool	Description
firebase_auth_get_user	Get user by UID or email
firebase_auth_list_users	List users (paginated, max 1000)
firebase_auth_create_user	Create a new user
firebase_auth_update_user	Update user properties
firebase_auth_delete_user	Delete a user
firebase_auth_set_custom_claims	Set custom claims (roles, permissions)

📄 Firestore Tools

Tool	Description
firestore_list_collections	List top-level or sub-collections
firestore_get_document	Get a single document by path
firestore_list_documents	List documents in a collection (paginated)
firestore_query_documents	Query with where/orderBy/limit filters
firestore_count_documents	Count documents (with optional filters)
firestore_set_document	Create or overwrite a document
firestore_update_document	Update specific fields
firestore_delete_document	Delete a document

📦 Storage Tools

Tool	Description
storage_list_files	List files & folders in a bucket (with prefix filter, pagination)
storage_get_file_metadata	Get file metadata (size, content type, timestamps, custom metadata)
storage_get_download_url	Get a Firebase download URL for a file
storage_get_signed_url	Generate a temporary signed URL (read or write, up to 7 days)
storage_upload	Upload text or base64 content to a file
storage_download	Download a file as text or base64 (max 10MB)
storage_delete_file	Delete a file
storage_copy_file	Copy a file (same or different bucket)
storage_move_file	Move / rename a file

Usage Examples

Once connected, you can ask your AI assistant things like:

"List all collections in Firestore"

"Show me the first 10 users in Firebase Auth"

"Query the 'orders' collection for all orders where status == 'pending'"

"Get the document at users/abc123"

"Count how many documents are in the 'products' collection"

"Update the user with UID xyz to set displayName to 'John Doe'"

"List all files in the 'images/' folder in Storage"

"Upload this JSON to storage at 'exports/data.json'"

"Generate a signed download URL for 'reports/monthly.pdf' that expires in 24 hours"

Special Field Values (for writes)

The Firestore write tools support special field values:

// Server timestamp
{ "_type": "serverTimestamp" }

// Increment a number field
{ "_type": "increment", "value": 5 }

// Add to an array field
{ "_type": "arrayUnion", "elements": ["tag1", "tag2"] }

// Remove from an array field
{ "_type": "arrayRemove", "elements": ["tag1"] }

// Delete a field
{ "_type": "delete" }

Project Structure

firebase-mcp/
├── src/
│   ├── index.ts          # CLI entry point with arg parsing
│   ├── firebase.ts       # Dynamic credential loading & Firebase init
│   ├── utils.ts          # Serialization & helpers
│   └── tools/
│       ├── auth.ts       # Firebase Auth tools (6)
│       ├── firestore.ts  # Firestore tools (8)
│       └── storage.ts    # Firebase Storage tools (9)
├── dist/                 # Compiled output (after build)
├── package.json
├── tsconfig.json
└── README.md

Security Notes

⚠️ Never commit your service account key to git!

Make sure .firebase/ is in your .gitignore:

.firebase/

The service account key grants full admin access to your Firebase project. Treat it like a password.

Large Outputs

Read operations that return more than the configured threshold (large collections, big documents, long file listings) are not truncated. Instead, the full result is written to a temporary file and the tool returns a short message telling the LLM the output was too large, along with the filePath to read:

{
  "status": "output_too_large",
  "message": "The output was too large to return inline. The full result has been written to the file below. Read that file to access the complete data.",
  "filePath": "/tmp/firebase-mcp-XXXXXX/output.json",
  "totalChars": 128034,
  "threshold": 25000
}

This keeps the model's context from being flooded while ensuring no data is lost — the client can read the file on demand. Temp files are written to the OS temp directory (os.tmpdir()).

Configuring the threshold

The threshold (in characters) is resolved in this order:

1. --max-output-size <chars> CLI flag
2. FIREBASE_MCP_MAX_OUTPUT environment variable
3. Default: 25000 characters

# via CLI flag
firebase-mcp --max-output-size 40000

# via environment variable
FIREBASE_MCP_MAX_OUTPUT=40000 firebase-mcp

Invalid values (non-numeric or ≤ 0) are ignored with a warning and the default is used.

License

MIT