Firestore

You run a Model Context Protocol (MCP) server to enable an AI assistant to interact with your Firebase Firestore data directly. This server handles common data operations, including creating, reading, updating, and deleting documents, as well as listing collections, counting documents, and performing filtered queries, while automatically converting Firestore data types.

How to use

You connect your MCP-enabled AI assistant to the Firestore MCP Server and start issuing data-centric requests. Use the available tools to manage your Firestore data through natural-language prompts. Typical workflows include listing top-level collections, exploring subcollections for a given document, counting documents in a collection, retrieving specific documents, creating new documents, updating existing ones, deleting documents, and performing filtered queries to fetch just the data you need.

How to install

# 1. Clone the repository
git clone https://github.com/your-username/firestore-mcp.git
cd firestore-mcp

# 2. Install dependencies
npm install

# 3. Configure Firebase credentials
# Copy example environment file and customize values
cp .env.example .env

# 4. Build the project
npm run build

Project-level configuration for the MCP server is defined in a project root file named .mcp.json. Create the file and specify the stdio-based server command to launch the Firestore MCP Server. The server loads environment variables from the installation directory to keep credentials secure.

{
  "mcpServers": {
    "firestore": {
      "command": "node",
      "args": ["/path/to/firestore-mcp/dist/index.js"]
    }
  }
}

If you prefer inline environment variables rather than a .env file, you can provide them directly in the configuration. The following example shows how to supply credentials inline in the same configuration structure.

{
  "mcpServers": {
    "firestore": {
      "command": "node",
      "args": ["/path/to/firestore-mcp/dist/index.js"],
      "env": {
        "FIREBASE_PROJECT_ID": "your-project-id",
        "FIREBASE_CLIENT_EMAIL": "your-client-email",
        "FIREBASE_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n"
      }
    }
  }
}

After configuring, restart the MCP client (Claude Code) and approve the MCP server when prompted. The Firestore tools will then be available in your conversation.

Additional sections

Configuration options, security considerations, and troubleshooting steps are important to keep your integration secure and reliable.

Security and configuration notes

• Never commit credentials in environment files. Protect service account keys and restrict permissions to only what is necessary for Firestore access. Consider read-only service accounts for development to prevent accidental data changes. Rotate credentials periodically.

Troubleshooting

If you encounter permission errors, verify your service account has Firestore access and that all credential values (project ID, client email, private key) are correct. Ensure the private key preserves newline characters as literal \n in the configuration. If the MCP server status shows failure, confirm the environment file exists in the installed server directory and run the launch command manually to surface error messages.

Available tools

list_collections

List all top-level collections in the Firestore database.

list_subcollections

List subcollections under a specific document path.

count_documents

Count documents within a collection without fetching all documents.

get_document

Retrieve a single document by its path.

list_documents

List documents in a collection with an optional limit.

create_document

Create a new document in a collection with provided data and optional documentId.

update_document

Update an existing document with new data, optionally merging with existing data.

delete_document

Delete a document at the specified path.

query_documents

Query documents in a collection using a field, operator, and value with an optional limit.