@theihtisham/mcp-server-firebase 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,362 @@
+# MCP Server Firebase
+
+[![npm version](https://img.shields.io/npm/v/mcp-server-firebase.svg)](https://www.npmjs.com/package/mcp-server-firebase)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+[![TypeScript Strict](https://img.shields.io/badge/typescript-strict-blue.svg)](https://www.typescriptlang.org/)
+[![Vitest](https://img.shields.io/badge/tested_with-vitest-6da13f.svg)](https://vitest.dev/)
+
+> **Give AI assistants full Firebase superpowers -- manage Firestore, Auth, Storage, and more through natural language.**
+
+An MCP (Model Context Protocol) server that provides AI assistants like Claude with complete access to Firebase services. Query Firestore, manage users, upload files, send notifications, and more -- all through conversational AI.
+
+---
+
+## Features
+
+- **37 tools** across 6 Firebase services
+- **Firestore**: Query, CRUD, batch writes, transactions, aggregation, real-time listeners, schema inference
+- **Auth**: Create, read, update, delete users, verify tokens, manage custom claims
+- **Storage**: Upload, download, list, delete files, generate signed URLs
+- **Realtime DB**: Full CRUD with advanced querying (orderBy, filters, limits)
+- **Cloud Functions**: List, trigger, read logs
+- **Messaging (FCM)**: Send notifications, multicast, topic subscriptions
+- **Secure by default**: Input validation, NoSQL injection prevention, path traversal protection
+- **Production-ready**: LRU caching, automatic pagination, connection pooling, structured errors with fix suggestions
+- **Type-safe**: TypeScript strict mode with comprehensive Zod-style validation
+
+---
+
+## Demo Conversation
+
+```
+User: Show me all users who signed up this week
+
+AI: I'll query the users collection, filtering by creation date.
+
+  [calls firestore_query with:
+    collection: "users"
+    where: [{ field: "createdAt", operator: ">=", value: "2026-04-04" }]
+    orderBy: [{ field: "createdAt", direction: "desc" }]
+  ]
+
+  Found 23 users who signed up since April 4th. Here are the most recent:
+
+  | Name          | Email                | Joined        |
+  |---------------|----------------------|---------------|
+  | Jane Smith    | jane@example.com     | Apr 9, 18:42  |
+  | Bob Wilson    | bob@example.com      | Apr 9, 15:11  |
+  | Alice Chen    | alice@example.com    | Apr 8, 22:03  |
+  ... and 20 more.
+
+User: Send a welcome notification to Jane
+
+AI: I'll send a push notification to Jane's devices.
+
+  [calls auth_get_user with email: "jane@example.com"]
+  [calls messaging_send with:
+    topic: "user_jane_smith"
+    notification: { title: "Welcome!", body: "Thanks for joining us, Jane!" }
+  ]
+
+  Notification sent successfully! Message ID: projects/myapp/messages/123456
+
+User: What's the schema of the orders collection?
+
+AI: Let me infer the schema by sampling documents.
+
+  [calls firestore_infer_schema with:
+    collection: "orders"
+    sampleSize: 20
+  ]
+
+  Here's the inferred schema for `orders`:
+
+  | Field        | Type     | Presence | Nullable |
+  |-------------|----------|----------|----------|
+  | customerId  | string   | 100%     | No       |
+  | items       | array    | 100%     | No       |
+  | total       | number   | 100%     | No       |
+  | status      | string   | 95%      | No       |
+  | notes       | string   | 40%      | Yes      |
+  | shippedAt   | timestamp| 60%      | Yes      |
+```
+
+---
+
+## Installation
+
+### Quick Start (Claude Desktop)
+
+1. Install the package globally:
+
+```bash
+npm install -g mcp-server-firebase
+```
+
+2. Add to your Claude Desktop config (`~/AppData/Roaming/Claude/claude_desktop_config.json` on Windows or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "firebase": {
+      "command": "mcp-server-firebase",
+      "env": {
+        "FIREBASE_SERVICE_ACCOUNT_PATH": "/path/to/service-account-key.json"
+      }
+    }
+  }
+}
+```
+
+### From Source
+
+```bash
+git clone https://github.com/your-username/mcp-server-firebase.git
+cd mcp-server-firebase
+npm install
+npm run build
+```
+
+Then configure Claude Desktop to use the built version:
+
+```json
+{
+  "mcpServers": {
+    "firebase": {
+      "command": "node",
+      "args": ["/path/to/mcp-server-firebase/dist/index.js"],
+      "env": {
+        "FIREBASE_SERVICE_ACCOUNT_PATH": "/path/to/service-account-key.json"
+      }
+    }
+  }
+}
+```
+
+### Authentication Options
+
+The server supports multiple ways to authenticate with Firebase:
+
+| Method | Environment Variable | Description |
+|--------|---------------------|-------------|
+| Service Account JSON string | `FIREBASE_SERVICE_ACCOUNT_KEY` | Full JSON as a single-line string |
+| Service Account file path | `FIREBASE_SERVICE_ACCOUNT_PATH` | Path to JSON key file |
+| Individual fields | `FIREBASE_PROJECT_ID`, `FIREBASE_CLIENT_EMAIL`, `FIREBASE_PRIVATE_KEY` | Separate env vars |
+| Application Default Credentials | _(none needed)_ | Works on GCP, with `gcloud auth` |
+
+Optional configuration:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `FIREBASE_STORAGE_BUCKET` | Cloud Storage bucket name | Auto-detected from project |
+| `FIREBASE_DATABASE_URL` | Realtime Database URL | Auto-detected from project |
+| `FIREBASE_FUNCTIONS_REGION` | Cloud Functions region | `us-central1` |
+
+---
+
+## Tools Reference
+
+### Firestore (13 tools)
+
+| Tool | Description |
+|------|-------------|
+| `firestore_query` | Query collections with where, orderBy, limit, and pagination |
+| `firestore_get_document` | Get a single document by path |
+| `firestore_add_document` | Add a document with auto-generated ID |
+| `firestore_set_document` | Create or overwrite a document (with optional merge) |
+| `firestore_update_document` | Update specific fields (supports dot notation) |
+| `firestore_delete_document` | Delete a document (optionally recursive) |
+| `firestore_batch_write` | Atomic batch of up to 500 write operations |
+| `firestore_transaction` | Read-then-write transaction for conditional updates |
+| `firestore_list_collections` | List root collections or subcollections of a document |
+| `firestore_list_subcollections` | List subcollections of a specific document |
+| `firestore_aggregate_query` | Count, sum, average with optional filters |
+| `firestore_listen_changes` | Listen for real-time changes (time-windowed) |
+| `firestore_infer_schema` | Infer collection schema by sampling documents |
+
+### Auth (7 tools)
+
+| Tool | Description |
+|------|-------------|
+| `auth_create_user` | Create a new user (email, phone, password, etc.) |
+| `auth_get_user` | Get user by UID, email, or phone number |
+| `auth_list_users` | List users with pagination |
+| `auth_update_user` | Update user properties |
+| `auth_delete_user` | Delete a user |
+| `auth_verify_token` | Verify and decode a Firebase ID token |
+| `auth_set_custom_claims` | Set RBAC claims on a user |
+
+### Storage (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `storage_upload_file` | Upload a base64-encoded file |
+| `storage_download_file` | Download a file (returns base64) |
+| `storage_list_files` | List files with prefix filtering and pagination |
+| `storage_delete_file` | Delete a file |
+| `storage_get_signed_url` | Generate a time-limited signed URL |
+| `storage_get_metadata` | Get file metadata (size, type, hashes) |
+
+### Realtime Database (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `rtdb_get_data` | Read data at a path |
+| `rtdb_set_data` | Overwrite data at a path |
+| `rtdb_push_data` | Push to a list with auto-generated key |
+| `rtdb_update_data` | Update specific fields without full overwrite |
+| `rtdb_remove_data` | Remove data at a path |
+| `rtdb_query_data` | Query with orderBy, filters, and limits |
+
+### Cloud Functions (3 tools)
+
+| Tool | Description |
+|------|-------------|
+| `functions_list` | List deployed Cloud Functions |
+| `functions_trigger` | Trigger an HTTP Cloud Function |
+| `functions_get_logs` | Get recent logs for a function |
+
+### Messaging (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `messaging_send` | Send a notification to a device, topic, or condition |
+| `messaging_send_multicast` | Send to up to 500 devices at once |
+| `messaging_subscribe_topic` | Subscribe tokens to a topic |
+| `messaging_unsubscribe_topic` | Unsubscribe tokens from a topic |
+
+---
+
+## Query Builder Examples
+
+### Firestore Query with Multiple Filters
+
+```json
+{
+  "collection": "orders",
+  "where": [
+    { "field": "status", "operator": "==", "value": "active" },
+    { "field": "total", "operator": ">", "value": 100 }
+  ],
+  "orderBy": [{ "field": "total", "direction": "desc" }],
+  "limit": 50
+}
+```
+
+### Pagination
+
+```json
+{
+  "collection": "products",
+  "limit": 100,
+  "pageToken": "cHJvZHVjdHMvcHJvZDEyMw=="
+}
+```
+
+### Aggregation
+
+```json
+{
+  "collection": "orders",
+  "aggregations": [
+    { "type": "count", "alias": "totalOrders" },
+    { "type": "sum", "field": "total", "alias": "revenue" },
+    { "type": "avg", "field": "total", "alias": "averageOrder" }
+  ],
+  "where": [
+    { "field": "status", "operator": "==", "value": "completed" }
+  ]
+}
+```
+
+### Realtime DB Query
+
+```json
+{
+  "path": "/scores",
+  "orderBy": { "child": "score" },
+  "limitToLast": 10
+}
+```
+
+---
+
+## Security
+
+This server is designed with security as a priority:
+
+- **Service account key via environment variable** -- never hardcoded or committed
+- **Input validation** on every parameter (paths, emails, UIDs, limits)
+- **NoSQL injection prevention** -- field names starting with `$` or containing `.` are rejected
+- **Path traversal prevention** -- storage paths with `..` or leading `/` are blocked
+- **Field name restrictions** -- where clause fields starting with `__` are rejected
+- **Custom claims size limit** -- enforces Firebase's 1000-byte limit
+- **Reserved claim keys** -- prevents overwriting standard JWT claims
+- **Batch operation limits** -- caps at 500 operations per batch
+- **Signed URL limits** -- minimum 60s, maximum 7 days validity
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run with coverage
+npm run test:coverage
+
+# Type check
+npm run lint
+
+# Run locally
+npm run dev
+```
+
+### Project Structure
+
+```
+src/
+  index.ts              # MCP server entry point
+  services/
+    firebase.ts         # Firebase Admin SDK initialization
+  tools/
+    types.ts            # ToolDefinition interface
+    index.ts            # Tool aggregation and export
+    firestore.ts        # 13 Firestore tools
+    auth.ts             # 7 Auth tools
+    storage.ts          # 6 Storage tools
+    realtime-db.ts      # 6 Realtime DB tools
+    functions.ts        # 3 Cloud Functions tools
+    messaging.ts        # 4 FCM Messaging tools
+  utils/
+    index.ts            # Re-exports
+    validation.ts       # Input validation and sanitization
+    errors.ts           # Error handling with fix suggestions
+    cache.ts            # LRU cache with TTL and prefix invalidation
+    pagination.ts       # Cursor-based pagination utilities
+tests/
+  validation.test.ts    # Validation tests (16 tests)
+  errors.test.ts        # Error handling tests (10 tests)
+  cache.test.ts         # Cache tests (12 tests)
+  pagination.test.ts    # Pagination tests (4 tests)
+  tools.test.ts         # Tool registration and validation tests (30+ tests)
+  firebase-service.test.ts  # RTDB path validation tests
+vitest.config.ts
+```
+
+---
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const firebase_js_1 = require("./services/firebase.js");
+const index_js_2 = require("./tools/index.js");
+const SERVER_NAME = 'mcp-server-firebase';
+const SERVER_VERSION = '1.0.0';
+async function main() {
+    // Validate Firebase configuration on startup
+    try {
+        (0, firebase_js_1.initializeFirebase)();
+    }
+    catch (err) {
+        console.error(`Failed to initialize Firebase: ${err.message}\n` +
+            'Ensure one of the following is set:\n' +
+            '  - FIREBASE_SERVICE_ACCOUNT_KEY (JSON string)\n' +
+            '  - FIREBASE_SERVICE_ACCOUNT_PATH (file path)\n' +
+            '  - FIREBASE_PROJECT_ID + FIREBASE_CLIENT_EMAIL + FIREBASE_PRIVATE_KEY\n' +
+            '  - Application Default Credentials (gcloud auth application-default login)');
+        process.exit(1);
+    }
+    // Create MCP server using the low-level Server class
+    // This allows us to register tools with raw JSON Schema input schemas
+    const server = new index_js_1.Server({ name: SERVER_NAME, version: SERVER_VERSION }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // Build a map for quick tool lookup
+    const toolMap = new Map(index_js_2.allTools.map((t) => [t.name, t]));
+    // Handle tools/list requests
+    server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
+        return {
+            tools: index_js_2.allTools.map((tool) => ({
+                name: tool.name,
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+            })),
+        };
+    });
+    // Handle tools/call requests
+    server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+        const toolName = request.params.name;
+        const tool = toolMap.get(toolName);
+        if (!tool) {
+            return {
+                content: [{ type: 'text', text: `Error: Unknown tool "${toolName}".` }],
+                isError: true,
+            };
+        }
+        try {
+            const args = request.params.arguments ?? {};
+            const result = await tool.handler(args);
+            return {
+                content: [{ type: 'text', text: result }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: 'text', text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    });
+    // Connect using stdio transport
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error(`${SERVER_NAME} v${SERVER_VERSION} running on stdio`);
+    console.error(`Registered ${index_js_2.allTools.length} tools`);
+}
+main().catch((err) => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/services/firebase.d.ts

@@ -0,0 +1,14 @@
+import * as admin from 'firebase-admin';
+export interface FirebaseConfig {
+    projectId?: string;
+    storageBucket?: string;
+    databaseURL?: string;
+}
+export declare function initializeFirebase(config?: FirebaseConfig): admin.app.App;
+export declare function getFirestore(): admin.firestore.Firestore;
+export declare function getAuth(): admin.auth.Auth;
+export declare function getStorage(): admin.storage.Storage;
+export declare function getRealtimeDb(): admin.database.Database;
+export declare function getMessaging(): admin.messaging.Messaging;
+export declare function getApp(): admin.app.App;
+//# sourceMappingURL=firebase.d.ts.map

package/dist/services/firebase.js

@@ -0,0 +1,163 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initializeFirebase = initializeFirebase;
+exports.getFirestore = getFirestore;
+exports.getAuth = getAuth;
+exports.getStorage = getStorage;
+exports.getRealtimeDb = getRealtimeDb;
+exports.getMessaging = getMessaging;
+exports.getApp = getApp;
+const admin = __importStar(require("firebase-admin"));
+const fs_1 = __importDefault(require("fs"));
+let app = null;
+function getServiceAccount() {
+    // 1. Try FIREBASE_SERVICE_ACCOUNT_KEY (JSON string)
+    const keyEnv = process.env['FIREBASE_SERVICE_ACCOUNT_KEY'];
+    if (keyEnv) {
+        try {
+            return JSON.parse(keyEnv);
+        }
+        catch {
+            throw new Error('FIREBASE_SERVICE_ACCOUNT_KEY is set but contains invalid JSON. ' +
+                'Provide the full service account JSON as a single-line string.');
+        }
+    }
+    // 2. Try FIREBASE_SERVICE_ACCOUNT_PATH (file path)
+    const pathEnv = process.env['FIREBASE_SERVICE_ACCOUNT_PATH'];
+    if (pathEnv) {
+        try {
+            const content = fs_1.default.readFileSync(pathEnv, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch (err) {
+            throw new Error(`Failed to read service account file at "${pathEnv}": ${err.message}. ` +
+                'Ensure the path is correct and the file is valid JSON.');
+        }
+    }
+    // 3. Try individual env vars
+    const projectId = process.env['FIREBASE_PROJECT_ID'];
+    const clientEmail = process.env['FIREBASE_CLIENT_EMAIL'];
+    const privateKey = process.env['FIREBASE_PRIVATE_KEY']?.replace(/\\n/g, '\n');
+    if (projectId && clientEmail && privateKey) {
+        return { projectId, clientEmail, privateKey };
+    }
+    // 4. Return undefined — rely on Application Default Credentials (ADC)
+    return undefined;
+}
+function initializeFirebase(config) {
+    if (app) {
+        return app;
+    }
+    const serviceAccount = getServiceAccount();
+    const initOptions = {};
+    if (serviceAccount) {
+        initOptions.credential = admin.credential.cert(serviceAccount);
+    }
+    // If no service account, ADC will be used (works on GCP, with gcloud CLI, etc.)
+    if (config?.projectId) {
+        initOptions.projectId = config.projectId;
+    }
+    else if (serviceAccount?.projectId) {
+        initOptions.projectId = serviceAccount.projectId;
+    }
+    else {
+        const envProject = process.env['FIREBASE_PROJECT_ID'];
+        if (envProject) {
+            initOptions.projectId = envProject;
+        }
+    }
+    if (config?.storageBucket) {
+        initOptions.storageBucket = config.storageBucket;
+    }
+    else {
+        const envBucket = process.env['FIREBASE_STORAGE_BUCKET'];
+        if (envBucket) {
+            initOptions.storageBucket = envBucket;
+        }
+    }
+    if (config?.databaseURL) {
+        initOptions.databaseURL = config.databaseURL;
+    }
+    else {
+        const envDbUrl = process.env['FIREBASE_DATABASE_URL'];
+        if (envDbUrl) {
+            initOptions.databaseURL = envDbUrl;
+        }
+    }
+    try {
+        app = admin.initializeApp(initOptions, 'mcp-firebase-server');
+    }
+    catch (err) {
+        // If app already exists, get it
+        if (err instanceof Error && err.message.includes('already exists')) {
+            app = admin.app('mcp-firebase-server');
+        }
+        else {
+            throw err;
+        }
+    }
+    return app;
+}
+function getFirestore() {
+    const firebaseApp = initializeFirebase();
+    return firebaseApp.firestore();
+}
+function getAuth() {
+    const firebaseApp = initializeFirebase();
+    return firebaseApp.auth();
+}
+function getStorage() {
+    const firebaseApp = initializeFirebase();
+    return firebaseApp.storage();
+}
+function getRealtimeDb() {
+    const firebaseApp = initializeFirebase();
+    return firebaseApp.database();
+}
+function getMessaging() {
+    const firebaseApp = initializeFirebase();
+    return firebaseApp.messaging();
+}
+function getApp() {
+    if (!app) {
+        return initializeFirebase();
+    }
+    return app;
+}
+//# sourceMappingURL=firebase.js.map

package/dist/tools/auth.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from './types.js';
+export declare const authTools: ToolDefinition[];
+//# sourceMappingURL=auth.d.ts.map