Google Cloud Firestore MCP Server

Common errors

• Error: GOOGLE_APPLICATION_CREDENTIALS environment variable is not set.

  cause The server failed to find the path to the Google service account credentials file.
  fix Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the absolute path of your service account JSON key file (e.g., `export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json`).

• Error: FIREBASE_PROJECT_ID environment variable is not set.

  cause The Firebase/Google Cloud project ID was not provided to the server.
  fix Set the `FIREBASE_PROJECT_ID` environment variable to your specific project ID (e.g., `export FIREBASE_PROJECT_ID=my-gcp-project-123`).

• FirebaseError: The project ID is not set. Either specify a project ID via the 'projectId' property in the options object or set the GOOGLE_CLOUD_PROJECT environment variable.

  cause Despite setting environment variables, the Firestore client could not pick up the project ID, possibly due to incorrect loading or application default credentials issues.
  fix Ensure `FIREBASE_PROJECT_ID` is correctly loaded. For programmatic usage, explicitly pass `projectId` in the configuration object to `startMCPServer`. For CLI/agent usage, verify the client's configuration for passing the project ID.

Warnings

• gotcha The `delete_collection` tool is powerful and, if used incorrectly, can permanently erase an entire Firestore collection and all its documents without confirmation. Use with extreme caution.
  Fix: Always double-check the target collection ID and ensure proper authorization before invoking `delete_collection`. Consider implementing additional safeguards in your client application if exposing this tool broadly.
• breaking This package requires Node.js version 18 or higher. Running with older Node.js versions will result in execution errors due to modern JavaScript features and API dependencies.
  Fix: Upgrade your Node.js environment to version 18.0.0 or higher. Use a Node Version Manager (nvm) for easy switching: `nvm install 18 && nvm use 18`.
• gotcha Correct configuration of `GOOGLE_APPLICATION_CREDENTIALS` and `FIREBASE_PROJECT_ID` environment variables is crucial for the server to authenticate with Google Cloud Firestore. Incorrect paths or missing variables will lead to authentication failures.
  Fix: Ensure `GOOGLE_APPLICATION_CREDENTIALS` points to the correct, accessible path of your service account JSON file and `FIREBASE_PROJECT_ID` matches your Firebase/GCP project ID. Verify file permissions for the credentials file.

Install

• npm install mcpfirestoredb npm
• yarn add mcpfirestoredb yarn
• pnpm add mcpfirestoredb pnpm

Imports

• startMCPServer
  wrong:

  const { startMCPServer } = require('mcpfirestoredb');

  correct:

  import { startMCPServer } from 'mcpfirestoredb';

  Primarily an ESM-only package since Node.js 18. This function programmatically initiates the MCP FirestoreDB server, often used for embedding, testing, or custom deployment scenarios.
• FirestoreMCPServerConfig

  import type { FirestoreMCPServerConfig } from 'mcpfirestoredb';

  Type definition for configuring the MCP FirestoreDB server programmatically, including essential settings like `projectId` and `credentialsPath`.
• MCPTool

  import type { MCPTool } from 'mcpfirestoredb';

  Represents the base interface or type for a tool exposed by the MCP server. Useful for introspection or custom tool development within the server's architecture, not for direct client-side tool execution.

Quickstart

This quickstart demonstrates how to programmatically start the MCP FirestoreDB server, loading necessary Google Cloud credentials from environment variables. It showcases basic initialization for integration into a Node.js application.

import { startMCPServer } from 'mcpfirestoredb';
import dotenv from 'dotenv';
import path from 'path';

dotenv.config(); // Load environment variables from .env

// Ensure required environment variables are set
if (!process.env.GOOGLE_APPLICATION_CREDENTIALS) {
  console.error('Error: GOOGLE_APPLICATION_CREDENTIALS environment variable is not set. Please provide the path to your service account JSON file.');
  process.exit(1);
}
if (!process.env.FIREBASE_PROJECT_ID) {
  console.error('Error: FIREBASE_PROJECT_ID environment variable is not set. Please provide your Google Cloud Project ID.');
  process.exit(1);
}

async function runServer() {
  try {
    console.log('Starting MCP FirestoreDB Server...');
    const serverInstance = await startMCPServer({
      projectId: process.env.FIREBASE_PROJECT_ID,
      credentialsPath: process.env.GOOGLE_APPLICATION_CREDENTIALS,
      databaseId: process.env.FIRESTORE_DATABASE_ID || '(default)', // Optional
      emulatorHost: process.env.FIRESTORE_EMULATOR_HOST // Optional
    });
    console.log(`MCP FirestoreDB Server started successfully on port ${serverInstance.port || 'default'}.`);
    console.log('Ready to receive commands from MCP-compatible clients.');
  } catch (error) {
    console.error('Failed to start MCP FirestoreDB Server:', error);
    process.exit(1);
  }
}

runServer();