mcpfirestoredb

library1.1.2jsnpmunverified

MCP FirestoreDB is a Node.js-based server that implements the Model Context Protocol (MCP) for Google Cloud Firestore operations. Currently at version 1.1.2, this package provides a robust set of 17 specialized tools, including document CRUD, batch operations, collection management, and advanced index configuration and analysis. It acts as an intermediary, enabling MCP-compatible clients (such as AI agents like Claude Desktop or Cursor IDE) to interact with Firestore databases via a standardized protocol. Key differentiators include its adherence to the MCP standard, comprehensive tooling for common and complex Firestore tasks (e.g., schema analysis, index generation), and capabilities for real-time operations, advanced querying, and high-performance batch processing. The package emphasizes production readiness with robust error handling and validation, and is primarily consumed by configuring it within an MCP client environment rather than requiring direct programmatic integration of its individual tools into an application. It provides the server-side logic for managing Firestore resources.

database gcp llm-agents

npm install mcpfirestoredb

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MCPFIRESTOREDB

mcpfirestoredb

databasejavascriptv1.1.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

startMCPServer

✓ import { startMCPServer } from 'mcpfirestoredb';

✗ const { startMCPServer } = require('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.

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();

Debug

Known issues

gotchaThe `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.

affects: >=1.0.0

breakingThis 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`.

affects: <18.0.0

gotchaCorrect 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.

affects: >=1.0.0

Errors

Common errors & fixes

Error: GOOGLE_APPLICATION_CREDENTIALS environment variable is not set.

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.

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.

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.

Upgrade

Version history

1.1.2latest on npm

Audit

Dependencies

@google-cloud/firestorerequiredCore dependency for interacting with Google Cloud Firestore database operations.

@modelcontextprotocol/sdkrequiredFramework or SDK for implementing the Model Context Protocol (MCP) server.

Agent activity

26 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/hendrickcastro/MCPFirestoreDB ↗

packagehttps://www.npmjs.com/package/mcpfirestoredb ↗

homepagehttps://mcpfirestoredb.com ↗