firebase-mcp

Exposes Firestore read, write, update, and delete operations as standardized MCP tools that AI clients can invoke. The FirebaseMcpServer class registers individual tool handlers (firestore_add_document, firestore_get_document, firestore_update_document, firestore_delete_document) that map directly to Firestore SDK methods, with schema-based parameter validation and error handling that converts Firebase exceptions into structured MCP responses. Each tool accepts collection path and document data as parameters, executes the operation against the initialized Firebase instance, and returns typed results (document IDs, success confirmations, or error details).

Implements firestore_list_documents and firestore_list_collections tools that traverse Firestore collection hierarchies and return paginated document snapshots. The implementation queries collections using the Firestore SDK, optionally applies client-side filtering based on field predicates passed as parameters, and returns structured arrays of documents with metadata. The tool supports nested collection discovery (listing subcollections within documents) and basic field-based filtering without requiring complex WHERE clause syntax, making it accessible to AI clients that may not be familiar with Firestore query syntax.

Implements storage_list_files tool that enumerates files in a Firebase Storage bucket with optional path prefix filtering. The tool queries the Storage bucket using the Admin SDK's listFiles() method, optionally filters results by a path prefix (e.g., 'uploads/2024/'), and returns an array of file metadata including name, size, creation date, and content type. The implementation supports pagination through a maxResults parameter, allowing large buckets to be enumerated incrementally. Results are returned as structured objects with file paths and metadata, enabling AI clients to discover and analyze bucket contents.

Implements firestore_add_document tool that creates new documents in Firestore collections with either auto-generated or specified document IDs. The tool accepts a collection path and document data, and optionally a document ID. If no ID is provided, Firestore generates a unique ID automatically using its ID generation algorithm. The implementation uses the Firestore SDK's add() method (for auto-ID) or set() method (for specified IDs), both of which are atomic operations. The tool returns the generated or specified document ID and optionally the full document snapshot, enabling AI clients to reference newly created documents.

Exposes Firebase Storage operations (storage_upload_file, storage_download_file, storage_list_files) as MCP tools that handle file I/O through the Storage SDK. The upload tool accepts base64-encoded file content and a destination path, writes to Storage, and returns a public download URL. The download tool retrieves files by path and returns base64-encoded content. The list tool enumerates files in a Storage bucket with optional path prefix filtering. All operations include error handling for authentication failures, missing files, and quota exceeded scenarios, with results formatted as structured MCP responses.

Exposes Firebase Authentication operations (auth_get_user, auth_list_users) as MCP tools that query the Firebase Auth service. The get_user tool retrieves a specific user's profile by UID or email, returning user metadata (creation date, last sign-in, email verification status, custom claims). The list_users tool enumerates all users in the project with pagination support. Both tools return sanitized user data (no password hashes or sensitive credentials) and include error handling for missing users or permission issues. The implementation uses the Firebase Admin SDK's Auth module to access user records.

Implements a transport layer that supports both HTTP and STDIO protocols for MCP communication, allowing the Firebase MCP server to integrate with different AI client architectures. The server initializes with a configurable transport mechanism (via environment variable or constructor parameter), handles protocol-specific serialization/deserialization, and manages connection lifecycle. HTTP transport exposes the MCP server on a specified port with standard HTTP request/response handling, while STDIO transport reads from stdin and writes to stdout, enabling integration with CLI-based AI tools and local development environments. The transport abstraction is handled by the MCP SDK, with the Firebase server providing configuration and tool registration.

Handles Firebase project initialization by reading service account credentials from environment variables or configuration files and initializing the Firebase Admin SDK. The FirebaseMcpServer constructor accepts a Firebase config object or reads from GOOGLE_APPLICATION_CREDENTIALS environment variable, validates the configuration, and initializes Firestore, Storage, and Auth service instances. The implementation follows Firebase Admin SDK patterns, creating singleton service instances that are reused across all tool handlers. Error handling includes validation of credential format, project ID verification, and graceful failure if Firebase services are unavailable.

Implements a tool registration system where each Firebase operation (Firestore CRUD, Storage operations, Auth queries) is registered as a named MCP tool with a JSON schema that defines required parameters, types, and descriptions. The FirebaseMcpServer class registers tools using the MCP SDK's tool registration API (src/index.ts 477-1334), providing each tool with a schema that specifies parameter names, types (string, number, boolean, object), required fields, and descriptions. When an AI client calls a tool, the MCP framework validates parameters against the schema before invoking the handler, ensuring type safety and providing clear error messages for invalid inputs. The schema-based approach enables AI clients to discover available tools and their parameter requirements without documentation.

Implements firestore_update_document tool that performs partial document updates using Firestore's merge semantics. Unlike add/set operations that replace entire documents, the update tool accepts a partial data object and merges it with existing document fields, preserving unspecified fields. The implementation uses the Firestore SDK's update() method which applies field-level updates atomically, supporting nested field updates via dot notation (e.g., 'user.profile.name'). The tool validates that the document exists before updating and returns the updated document snapshot or an error if the document is not found.

Implements comprehensive error handling across all Firebase operations, catching Firebase SDK exceptions (auth errors, permission denied, not found, quota exceeded) and translating them into structured MCP error responses. The error handling layer (src/index.ts 477-1334) wraps each tool handler in try-catch blocks, maps Firebase-specific error codes to human-readable messages, and returns error details in the MCP response format. Common error scenarios include missing documents (DOCUMENT_NOT_FOUND), permission failures (PERMISSION_DENIED), authentication issues (UNAUTHENTICATED), and quota limits (RESOURCE_EXHAUSTED). The implementation preserves error context (original error code, message) while providing clear guidance to AI clients about what went wrong.

Implements firestore_delete_document tool that removes documents from Firestore collections with optional existence checking. The tool accepts a collection path and document ID, validates that the document exists (optional), and executes the delete operation. The implementation uses Firestore's delete() method which is atomic and idempotent (deleting a non-existent document succeeds silently). The tool can be configured to fail if the document doesn't exist (strict mode) or succeed regardless (lenient mode), providing flexibility for different workflow requirements. Deletion is permanent and cannot be undone through the MCP interface.