MCP Firebase Server

Servidor MCP Firebase (Protocolo de Contexto de Modelo)

Este servidor implementa el Protocolo de Contexto de Modelo (MCP) para actuar como un puente entre un Modelo de Lenguaje Grande (LLM) como Claude y Firebase (Firestore). Permite que el LLM lea y escriba en colecciones de Firestore exponiendo estas operaciones como "herramientas" MCP.

Este servidor está construido usando el SDK oficial de Python mcp.

Requisitos previos

• Python 3.7+ (preferiblemente 3.8+ para asynccontextmanager y las características completas de sugerencias de tipo utilizadas por MCP)
• Pip (instalador de paquetes de Python) o uv (recomendado por la documentación de MCP para la gestión de proyectos)
• Un proyecto de Firebase con Firestore habilitado.
• Un archivo JSON de clave de cuenta de servicio de Firebase.

Configuración

1. Clonar/Descargar: Asegúrate de tener el archivo del servidor (mcp_firebase_server.py), requirements.txt, etc., en un directorio local.

2. Clave de cuenta de servicio:

   • El servidor necesita una clave de cuenta de servicio de Firebase para autenticarse.
   • Opción 1 (Recomendada para la configuración del cliente MCP): Establece la variable de entorno SERVICE_ACCOUNT_KEY_PATH a la ruta absoluta de tu archivo JSON de cuenta de servicio. Este es el método más flexible cuando el servidor es lanzado por un cliente MCP.
   • Opción 2 (Alternativa): Si la variable de entorno SERVICE_ACCOUNT_KEY_PATH no está establecida, el servidor buscará un archivo llamado serviceAccountKey.json en su propio directorio (el mismo directorio que mcp_firebase_server.py). Si usas este método, renombra tu archivo de clave en consecuencia.
   • Importante: Asegúrate de que tu archivo de clave de cuenta de servicio (como sea que se llame o se acceda) se mantenga seguro e idealmente listado en tu .gitignore si existe una copia local en el proyecto.

3. Bucket de almacenamiento de Firebase (Opcional):

   • Si tienes la intención de usar las funcionalidades de Firebase Storage con este servidor (actualmente ninguna herramienta lo usa, pero se puede agregar), establece la variable de entorno FIREBASE_STORAGE_BUCKET al nombre del bucket de almacenamiento de tu proyecto de Firebase (por ejemplo, your-project-id.appspot.com). El servidor leerá e imprimirá este valor si está establecido.

4. Crear un entorno virtual (Recomendado): Usando venv:

   python3 -m venv venv
   source venv/bin/activate  # On macOS/Linux
   # venv\\Scripts\\activate   # On Windows
   

   O, si usas uv (como sugiere la documentación de MCP para nuevos proyectos):

   uv venv
   source .venv/bin/activate # Or similar, depending on your uv setup
   

5. Instalar dependencias: Usando pip:

   pip install -r requirements.txt
   

   O, si usas uv:

   uv pip install -r requirements.txt
   

   Esto instalará mcp[cli] y firebase-admin.

Ejecutar el servidor

Hay un par de formas de ejecutar este servidor MCP:

1. Ejecución directa (para transporte stdio a través de run_server.sh): Se proporciona un script run_server.sh para simplificar el lanzamiento del servidor. Este script maneja la activación del entorno virtual (si se llama venv y está presente en la raíz del proyecto) antes de ejecutar el script de Python.

   Primero, haz que el script sea ejecutable:

   chmod +x run_server.sh
   

   Luego, ejecuta el servidor usando el script:

   ./run_server.sh
   

   Así es como un cliente MCP normalmente se configuraría para lanzar el servidor (consulta la sección "Uso con Claude" a continuación).

2. Usando la CLI de MCP para desarrollo e inspección (mcp dev): La CLI mcp (instalada como parte de mcp[cli]) proporciona un servidor de desarrollo y una herramienta de inspección. Esto es altamente recomendado durante el desarrollo.

   mcp dev mcp_firebase_server.py
   

   Esto iniciará el servidor y a menudo proporcionará una interfaz web para inspeccionar sus capacidades (herramientas, recursos) y realizar llamadas de prueba.

Herramientas MCP expuestas

Este servidor, llamado MCPFirebaseServer, expone las siguientes herramientas:

1. mcp_firebase_query_firestore_collection

• Descripción (del docstring): Recupera documentos de una colección de Firestore especificada.
• Argumentos:
  • collection_name (cadena, requerido): El nombre de la colección de Firestore a consultar.
  • limit (entero, opcional, predeterminado: 50): El número máximo de documentos a devolver.
• Devuelve: Una lista de documentos de la colección, o un mensaje de error.

2. mcp_firebase_add_document_to_firestore

• Descripción (del docstring): Agrega un nuevo documento con un ID generado automáticamente a la colección de Firestore especificada.
• Argumentos:
  • collection_name (cadena, requerido): El nombre de la colección de Firestore donde se agregará el documento.
  • document_data (objeto/diccionario, requerido): Un diccionario que representa el documento a agregar.
• Devuelve: Un diccionario que contiene el estado de éxito y el ID del nuevo documento, o un mensaje de error.

3. mcp_firebase_list_firestore_collections

• Descripción (del docstring): Lista todas las colecciones de nivel superior en la base de datos de Firestore.
• Argumentos:
  • random_string (cadena, requerido): Un parámetro ficticio (puede ser cualquier cadena) ya que esta herramienta no toma entrada significativa.
• Devuelve: Una lista de diccionarios, cada uno conteniendo el 'id' de una colección, o un mensaje de error.

4. mcp_firebase_get_firestore_document

• Descripción (del docstring): Recupera un documento específico de una colección de Firestore por su ID.
• Argumentos:
  • collection_name (cadena, requerido): El nombre de la colección de Firestore.
  • document_id (cadena, requerido): El ID del documento a recuperar.
• Devuelve: Un diccionario que representa los datos del documento, o un mensaje de error.

5. mcp_firebase_list_document_subcollections

• Descripción (del docstring): Lista todas las subcolecciones de un documento especificado en Firestore.
• Argumentos:
  • collection_name (cadena, requerido): El nombre de la colección principal.
  • document_id (cadena, requerido): El ID del documento cuyas subcolecciones se van a listar.
• Devuelve: Una lista de diccionarios, cada uno conteniendo el 'id' de una subcolección, o un mensaje de error.

6. mcp_firebase_update_firestore_document

• Descripción (del docstring): Actualiza un documento existente en una colección de Firestore especificada.
• Argumentos:
  • collection_name (cadena, requerido): El nombre de la colección de Firestore.
  • document_id (cadena, requerido): El ID del documento a actualizar.
  • update_data (objeto/diccionario, requerido): Un diccionario que contiene los campos a actualizar.
• Devuelve: Un diccionario que contiene el estado de éxito, o un mensaje de error.

7. mcp_firebase_query_firestore_collection_with_filter

• Descripción (del docstring): Recupera documentos de una colección de Firestore especificada, filtrando por valores de campo (solo igualdad ==).
• Argumentos:
  • collection_name (cadena, requerido): El nombre de la colección de Firestore a consultar.
  • filters (objeto/diccionario, requerido): Un diccionario donde las claves son nombres de campo y los valores son los valores para filtrar (por ejemplo, {"category": "electronics", "available": True}).
  • limit (entero, opcional, predeterminado: 50): El número máximo de documentos a devolver.
• Devuelve: Una lista de documentos de la colección que coinciden con los filtros, o un mensaje de error.

Uso con Claude (u otros clientes MCP)

Este servidor MCP de Firebase está diseñado para ejecutarse como un proceso separado, típicamente lanzado por una aplicación cliente MCP (como Claude Desktop o una aplicación personalizada construida con una plataforma como Windsurf que puede gestionar servidores MCP). El cliente luego se comunica con este servidor, usualmente a través de stdio (entrada/salida estándar) para servidores ejecutados localmente.

Pasos generales de integración:

1. Disponibilidad del servidor: Asegúrate de que mcp_firebase_server.py y sus dependencias (incluyendo serviceAccountKey.json) sean accesibles en el sistema donde el cliente MCP se ejecutará o pueda lanzar procesos.

2. Configuración del cliente: La aplicación cliente MCP necesita estar configurada para saber cómo iniciar tu MCPFirebaseServer. Esta configuración usualmente implica especificar:

   • Un comando a ejecutar (por ejemplo, python o uv run python).
   • Argumentos para ese comando (por ejemplo, la ruta a mcp_firebase_server.py).
   • Opcionalmente, cualquier variable de entorno que el servidor pueda necesitar (aunque nuestro servidor actual espera serviceAccountKey.json en el mismo directorio, una variable de entorno para la ruta de la clave podría ser una alternativa).

3. Lanzamiento y comunicación:

   • Cuando el cliente MCP necesite usar una herramienta proporcionada por este servidor, lanzará mcp_firebase_server.py usando el comando configurado.
   • El cliente y el servidor luego se comunican a través del protocolo MCP (por ejemplo, vía stdio). El cliente puede descubrir herramientas disponibles (como mcp_firebase_query_firestore_collection, mcp_firebase_add_document_to_firestore, etc.) y llamarlas.

Ejemplo conceptual de configuración (para un cliente MCP como Claude Desktop):

Muchas aplicaciones cliente compatibles con MCP (como Claude Desktop, como se referencia en la documentación de MCP) usan un archivo de configuración (a menudo JSON) para definir cómo lanzar y gestionar servidores MCP. Aunque el formato exacto puede variar según el cliente, el principio es similar.

A continuación se muestra un ejemplo conceptual basado en patrones vistos en la documentación de MCP. Necesitarías adaptar esto al mecanismo de configuración específico de tu cliente MCP elegido (Claude Desktop, Windsurf, etc.).

{
  "mcpServers": {
    "firebase": { // A unique name you assign to this server instance in the client's config
      "command": "/full/path/to/your/mc-firebase-server/run_server.sh", // IMPORTANT: Use the absolute path to the script
      "args": [], // Typically empty if run_server.sh handles everything
      // "cwd": "/full/path/to/your/mc-firebase-server/", // Usually not needed if run_server.sh cds to its own dir
      "env": {
        // Replace with the ACTUAL absolute path to your service account key file
        "SERVICE_ACCOUNT_KEY_PATH": "/path/to/your/serviceAccountKey.json", 
        // Optional: Replace with your actual Firebase Storage bucket name if needed by future tools
        "FIREBASE_STORAGE_BUCKET": "your-project-id.appspot.com" 
      }
    }
  }
}

Puntos clave para la configuración:

• "command": El ejecutable a ejecutar (por ejemplo, python). Asegúrate de que esté en el PATH del sistema o proporciona la ruta completa al intérprete de Python.
• "args": Una lista de argumentos. El primer argumento es típicamente el script a ejecutar. Es crucial usar la ruta completa y absoluta a mcp_firebase_server.py para asegurar que el cliente pueda encontrarlo, independientemente de dónde se lance el cliente.
• "cwd" (Directorio de trabajo actual): A veces, podrías necesitar especificar el directorio de trabajo para el proceso del servidor, especialmente si depende de rutas relativas para otros archivos (aunque nuestra ruta serviceAccountKey.json es relativa al script mismo, lo cual es generalmente robusto si la ruta del script es absoluta).
• "env": Para pasar variables de entorno. Aunque nuestro servidor actual localiza serviceAccountKey.json relativo a su propia ruta, un patrón común para servidores más configurables es pasar rutas de credenciales u otras configuraciones a través de variables de entorno. El SERVICE_ACCOUNT_KEY_PATH es crucial para la autenticación. El FIREBASE_STORAGE_BUCKET es opcional y actualmente no es usado por las herramientas proporcionadas, pero podría ser relevante si se agregan herramientas relacionadas con almacenamiento más adelante.

Flujo de interacción (Resumen):

1. El cliente inicia el servidor: El cliente MCP (usando la configuración anterior) inicia mcp_firebase_server.py.
2. El servidor se inicializa: Nuestro servidor intenta conectarse a Firebase.
3. Descubrimiento y llamadas de herramientas: El cliente descubre y llama herramientas como mcp_firebase_query_firestore_collection o mcp_firebase_add_document_to_firestore etc., según sea necesario.
4. El servidor responde: Los resultados se envían de vuelta al cliente a través de stdio.

Instrucciones específicas para Claude Desktop o Windsurf:

• Claude Desktop: Si estás usando Claude Desktop, consulta su documentación sobre cómo agregar y configurar servidores MCP personalizados. La estructura JSON anterior es un patrón común que podrías adaptar.
• Windsurf: Si Windsurf es tu orquestador y soporta la gestión de servidores MCP, tendrá su propio método para definir y lanzar estos servidores de herramientas externos. Necesitarías consultar la documentación de Windsurf para los detalles específicos, pero la información central (comando, argumentos para ejecutar mcp_firebase_server.py) será la misma.

Si tu cliente no tiene una interfaz de gestión de servidores MCP dedicada o archivo de configuración, pero puede ejecutar comandos de shell e interactuar a través de stdio, lanzarías programáticamente el script mcp_firebase_server.py y luego usarías una biblioteca de cliente MCP (como la de mcp.client.stdio) para comunicarte con él.

Desarrollo y pruebas

• Usa mcp dev mcp_firebase_server.py para ejecutar el servidor con el Inspector MCP. Esto te permite ver las herramientas descubiertas y probarlas interactivamente.
• Asegúrate de que serviceAccountKey.json esté colocado correctamente O que la variable de entorno SERVICE_ACCOUNT_KEY_PATH esté establecida cuando el servidor sea lanzado por un cliente MCP.
• Revisa la salida de consola del servidor para mensajes de inicialización de Firebase y cualquier error de tiempo de ejecución.

El script run_server.sh: El script run_server.sh en la raíz del proyecto está diseñado para:

1. Determinar su propia ubicación y cambiar el directorio actual a esa ubicación.
2. Localizar y activar un entorno virtual de Python llamado venv si existe en la raíz del proyecto.
3. Ejecutar el script mcp_firebase_server.py usando el intérprete python (idealmente desde el entorno virtual activado).

Este script asegura que el servidor MCP se ejecute en su entorno previsto. Recuerda hacerlo ejecutable (chmod +x run_server.sh).