MCP de Firebase

Descripción general

Firebase MCP permite que los asistentes de IA trabajen directamente con los servicios de Firebase, incluidos:

• Firestore : Operaciones de la base de datos de documentos

• Almacenamiento : Gestión de archivos con sólidas capacidades de carga

• Autenticación : gestión y verificación de usuarios

El servidor funciona con aplicaciones cliente MCP como Claude Desktop , Augment Code , VS Code y Cursor .

⚠️ Problema conocido : La herramienta firestore_list_collections puede devolver un error de validación de Zod en los registros del cliente. Se trata de un error de validación erróneo en el SDK de MCP, ya que nuestra investigación confirmó que no hay valores booleanos en la respuesta. A pesar del mensaje de error, la consulta sigue funcionando correctamente y devuelve los datos de la colección correctos. Este error afecta al registro y no afecta la funcionalidad.

Related MCP server: Firebase App Distribution API MCP Server

⚡ Inicio rápido

Prerrequisitos

• Proyecto de Firebase con credenciales de cuenta de servicio

• Entorno Node.js

1. Instalar el servidor MCP

Agregue la configuración del servidor a su archivo de configuración de MCP:

• Escritorio de Claude: ~/Library/Application Support/Claude/claude_desktop_config.json

• Aumento: ~/Library/Application Support/Code/User/settings.json

• Cursor: [project root]/.cursor/mcp.json

Los servidores MCP se pueden instalar manualmente o en tiempo de ejecución mediante npx (recomendado). La instalación determina la configuración:

Configurar para npx (recomendado)

{
  "firebase-mcp": {
    "command": "npx",
    "args": [
      "-y",
      "@gannonh/firebase-mcp"
    ],
    "env": {
      "SERVICE_ACCOUNT_KEY_PATH": "/absolute/path/to/serviceAccountKey.json",
      "FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app"
    }
  }
}

Configurar para instalación local

{
  "firebase-mcp": {
    "command": "node",
    "args": [
      "/absolute/path/to/firebase-mcp/dist/index.js"
    ],
    "env": {
      "SERVICE_ACCOUNT_KEY_PATH": "/absolute/path/to/serviceAccountKey.json",
      "FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app"
    }
  }
}

2. Pruebe la instalación

Pregúntele a su cliente de IA: "Pruebe todas las herramientas MCP de Firebase".

🛠️ Configuración y configuración

1. Configuración de Firebase

1. Vaya a Consola de Firebase → Configuración del proyecto → Cuentas de servicio

2. Haga clic en "Generar nueva clave privada".

3. Guarde el archivo JSON de forma segura

2. Variables de entorno

Requerido

• SERVICE_ACCOUNT_KEY_PATH : Ruta a la clave JSON de tu cuenta de servicio de Firebase (obligatorio)

Opcional

• FIREBASE_STORAGE_BUCKET : nombre del depósito para Firebase Storage (el valor predeterminado es [projectId].appspot.com )

• MCP_TRANSPORT : Tipo de transporte a utilizar ( stdio o http ) (predeterminado a stdio )

• MCP_HTTP_PORT : Puerto para transporte HTTP (predeterminado 3000 )

• MCP_HTTP_HOST : Host para el transporte HTTP (predeterminado en localhost )

• MCP_HTTP_PATH : Ruta para el transporte HTTP (predeterminado /mcp )

• DEBUG_LOG_FILE : Habilitar el registro de archivos:

  • Establezca en true para registrar en ~/.firebase-mcp/debug.log

  • Establezca una ruta de archivo para iniciar sesión en una ubicación personalizada

3. Integración del cliente

Escritorio de Claude

Editar: ~/Library/Application Support/Claude/claude_desktop_config.json

VS Code / Aumento

Editar: ~/Library/Application Support/Code/User/settings.json

Cursor

Editar: [project root]/.cursor/mcp.json

Referencia de API

Herramientas de Firestore

Herramientas de almacenamiento

Herramientas de autenticación

💻 Guía para desarrolladores

Instalación y construcción

git clone https://github.com/gannonh/firebase-mcp
cd firebase-mcp
npm install
npm run build

Ejecución de pruebas

Primero, instale e inicie los emuladores de Firebase:

npm install -g firebase-tools
firebase init emulators
firebase emulators:start

Luego ejecute las pruebas:

# Run tests with emulator
npm run test:emulator

# Run tests with coverage
npm run test:coverage:emulator

Estructura del proyecto

src/
├── index.ts                  # Server entry point
├── utils/                    # Utility functions
└── lib/
    └── firebase/              # Firebase service clients
        ├── authClient.ts     # Authentication operations
        ├── firebaseConfig.ts   # Firebase configuration
        ├── firestoreClient.ts # Firestore operations
        └── storageClient.ts  # Storage operations

🌐 Transporte HTTP

Firebase MCP ahora admite el transporte HTTP, además del transporte stdio predeterminado. Esto permite ejecutar el servidor como un servicio HTTP independiente al que pueden acceder varios clientes.

Ejecución con transporte HTTP

Para ejecutar el servidor con transporte HTTP:

# Using environment variables
MCP_TRANSPORT=http MCP_HTTP_PORT=3000 node dist/index.js

# Or with npx
MCP_TRANSPORT=http MCP_HTTP_PORT=3000 npx @gannonh/firebase-mcp

Configuración del cliente para HTTP

Al utilizar el transporte HTTP, configure su cliente MCP para conectarse al punto final HTTP:

{
  "firebase-mcp": {
    "url": "http://localhost:3000/mcp"
  }
}

Gestión de sesiones

El transporte HTTP admite la gestión de sesiones, lo que permite que varios clientes se conecten a la misma instancia de servidor. Cada cliente recibe un ID de sesión único que se utiliza para mantener el estado entre solicitudes.

🔍 Solución de problemas

Problemas comunes

Cubo de almacenamiento no encontrado

Si ve el error "El depósito especificado no existe":

1. Verificar el nombre de su depósito en Firebase Console → Almacenamiento

2. Establezca el nombre de depósito correcto en la variable de entorno FIREBASE_STORAGE_BUCKET

Error en la inicialización de Firebase

Si ves el error "Firebase no está inicializado":

1. Verifique que la ruta de la clave de su cuenta de servicio sea correcta y absoluta

2. Asegúrese de que la cuenta de servicio tenga los permisos adecuados para los servicios de Firebase

Índice compuesto requerido

Si recibe el error "Esta consulta requiere un índice compuesto":

1. Busque la URL proporcionada en el mensaje de error

2. Siga el enlace para crear el índice requerido en Firebase Console

3. Vuelva a intentar su consulta después de crear el índice (puede tardar unos minutos)

Error de validación de Zod con firestore_list_collections

Si ve un error de validación de Zod con el mensaje "Objeto esperado, booleano recibido" al usar la herramienta firestore_list_collections :

⚠️ Problema conocido : La herramienta firestore_list_collections puede devolver un error de validación de Zod en los registros del cliente. Se trata de un error de validación erróneo en el SDK de MCP, ya que nuestra investigación confirmó que no hay valores booleanos en la respuesta. A pesar del mensaje de error, la consulta sigue funcionando correctamente y devuelve los datos de la colección correctos. Este error afecta al registro y no afecta la funcionalidad.

Depuración

Habilitar el registro de archivos

Para ayudar a diagnosticar problemas, puede habilitar el registro de archivos:

# Log to default location (~/.firebase-mcp/debug.log)
DEBUG_LOG_FILE=true npx @gannonh/firebase-mcp

# Log to a custom location
DEBUG_LOG_FILE=/path/to/custom/debug.log npx @gannonh/firebase-mcp

También puede habilitar el inicio de sesión en la configuración de su cliente MCP:

{
  "firebase-mcp": {
    "command": "npx",
    "args": ["-y", "@gannonh/firebase-mcp"],
    "env": {
      "SERVICE_ACCOUNT_KEY_PATH": "/path/to/serviceAccountKey.json",
      "FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app",
      "DEBUG_LOG_FILE": "true"
    }
  }
}

Visualización de registros en tiempo real

Para ver los registros en tiempo real:

# Using tail to follow the log file
tail -f ~/.firebase-mcp/debug.log

# Using a split terminal to capture stderr
npm start 2>&1 | tee logs.txt

Uso del inspector MCP

El inspector MCP proporciona depuración interactiva:

# Install MCP Inspector
npm install -g @mcp/inspector

# Connect to your MCP server
mcp-inspector --connect stdio --command "node ./dist/index.js"

Formato de respuesta

Ejemplo de respuesta de carga de almacenamiento

{
  "name": "reports/quarterly.pdf",
  "size": "1024000",
  "contentType": "application/pdf",
  "updated": "2025-04-11T15:37:10.290Z",
  "downloadUrl": "https://storage.googleapis.com/bucket/reports/quarterly.pdf?alt=media",
  "bucket": "your-project.appspot.com"
}

Se muestra al usuario como:

## File Successfully Uploaded! 📁

Your file has been uploaded to Firebase Storage:

**File Details:**
- **Name:** reports/quarterly.pdf
- **Size:** 1024000 bytes
- **Type:** application/pdf
- **Last Updated:** April 11, 2025 at 15:37:10 UTC

**[Click here to download your file](https://storage.googleapis.com/bucket/reports/quarterly.pdf?alt=media)**

🤝 Contribuyendo

1. Bifurcar el repositorio

2. Crear una rama de características

3. Implementar cambios con pruebas (se requiere una cobertura del 80 % o más)

4. Enviar una solicitud de extracción

📄 Licencia

Licencia MIT: consulte el archivo de LICENCIA para obtener más detalles

Recursos relacionados

• Documentación del protocolo de contexto del modelo

• Documentación de Firebase

• SDK de administración de Firebase