MCP Firebase Server

Servidor Firebase MCP (Protocolo de contexto de modelo)

Este servidor implementa el Protocolo de Contexto de Modelo (MCP) para actuar como puente entre un Modelo de Lenguaje Grande (LLM) como Claude y Firebase (Firestore). Permite al LLM leer y escribir en colecciones de Firestore al exponer estas operaciones como herramientas de MCP.

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

Prerrequisitos

• Python 3.7+ (preferiblemente 3.8+ para asynccontextmanager y funciones de sugerencias de tipos completas 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úrese 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): Establezca la variable de entorno SERVICE_ACCOUNT_KEY_PATH con la ruta absoluta del archivo JSON de su cuenta de servicio. Este es el método más flexible cuando el servidor se inicia mediante un cliente MCP.
   • Opción 2 (Respaldo): Si la variable de entorno SERVICE_ACCOUNT_KEY_PATH no está configurada, el servidor buscará un archivo llamado serviceAccountKey.json en su propio directorio (el mismo directorio que mcp_firebase_server.py ). Si usa este método, cambie el nombre del archivo de clave según corresponda.
   • Importante: asegúrese de que el archivo de clave de su cuenta de servicio (independientemente de cómo se llame o se acceda a él) se mantenga seguro e idealmente aparezca en su .gitignore si existe una copia local en el proyecto.
3. Cubo de almacenamiento de Firebase (opcional):
   • Si desea usar las funcionalidades de Firebase Storage con este servidor (actualmente ninguna herramienta lo usa, pero se puede agregar), configure la variable de entorno FIREBASE_STORAGE_BUCKET con el nombre del depósito de almacenamiento de su proyecto de Firebase (p. ej., your-project-id.appspot.com ). El servidor leerá e imprimirá este valor si está configurado.
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 usa uv (como lo sugieren los documentos de MCP para proyectos nuevos):
   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 .

Ejecución del servidor

Hay un par de formas de ejecutar este servidor MCP:

1. Ejecución directa (para el transporte de stdio mediante run_server.sh ): Se proporciona un script run_server.sh para simplificar el inicio del servidor. Este script gestiona 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, haga que el script sea ejecutable:
   chmod +x run_server.sh
   Luego, ejecute el servidor usando el script:
   ./run_server.sh
   Así es como normalmente se configuraría un cliente MCP para iniciar el servidor (consulte la sección "Uso con Claude" a continuación).
2. **Uso de 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 muy recomendable 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. query_firestore_collection

• Descripción (de la cadena de documentación): recupera documentos de una colección de Firestore especificada.
• Argumentos:
  • collection_name (cadena, obligatoria): el nombre de la colección de Firestore que se consultará.
  • limit (entero, opcional, predeterminado: 50): el número máximo de documentos a devolver.
• Devuelve: (List[Dict[str, Any]]) Una lista de documentos de la colección. Cada documento es un diccionario con un campo id . Devuelve una lista con un único diccionario de errores si se produce un error (p. ej., [{"error": "Firestore not initialized..."}] o [{"error": "Failed to query..."}] ).

2. add_document_to_firestore

• Descripción (de la cadena de documentación): agrega un nuevo documento con una ID generada automáticamente a la colección de Firestore especificada.
• Argumentos:
  • collection_name (cadena, obligatoria): el nombre de la colección de Firestore donde se agregará el documento.
  • document_data (objeto/diccionario, obligatorio): un diccionario que representa el documento que se agregará.
• Devuelve: (Dict[str, Any]) Un diccionario que contiene success (booleano) y, en caso de éxito, id (cadena) y message (cadena), o error (cadena) en caso de error. Ejemplo: éxito: {"success": True, "id": "newDocId", "message": "Document added to 'logs'"} Ejemplo: error: {"success": False, "error": "Firestore not initialized..."}

Uso con Claude (u otros clientes MCP)

Este servidor Firebase de MCP está diseñado para ejecutarse como un proceso independiente, generalmente iniciado por una aplicación cliente de MCP (como Claude Desktop o una aplicación personalizada desarrollada con una plataforma como Windsurf que pueda administrar servidores MCP). El cliente se comunica con este servidor, generalmente mediante stdio (entrada/salida estándar) para servidores locales.

Pasos generales de integración:

1. Disponibilidad del servidor: asegúrese de que mcp_firebase_server.py y sus dependencias (incluido serviceAccountKey.json ) sean accesibles en el sistema donde el cliente MCP se ejecutará o puede iniciar procesos.
2. Configuración del cliente: La aplicación cliente MCP debe configurarse para saber cómo iniciar su MCPFirebaseServer . Esta configuración suele implicar especificar:
   • Un comando para 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 necesita utilizar una herramienta proporcionada por este servidor, iniciará mcp_firebase_server.py utilizando el comando configurado.
   • El cliente y el servidor se comunican mediante el protocolo MCP (p. ej., mediante stdio ). El cliente puede descubrir las herramientas disponibles ( query_firestore_collection , add_document_to_firestore ) e invocarlas.

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

Muchas aplicaciones cliente compatibles con MCP (como Claude Desktop, como se menciona en la documentación de MCP) utilizan un archivo de configuración (generalmente JSON) para definir cómo iniciar y administrar los servidores MCP. Si bien el formato exacto puede variar según el cliente, el principio es similar.

A continuación se muestra un ejemplo conceptual basado en patrones de la documentación de MCP. Deberá adaptarlo al mecanismo de configuración específico de su cliente MCP (Claude Desktop, Windsurf, etc.).

Puntos clave para la configuración:

• "command" : El ejecutable que se ejecutará (p. ej., python ). Asegúrese de que esté en la ruta del sistema o proporcione la ruta completa al intérprete de Python.
• "args" : Una lista de argumentos. El primer argumento suele ser el script a ejecutar. Es fundamental usar la ruta completa y absoluta a mcp_firebase_server.py para garantizar que el cliente pueda encontrarlo, independientemente de su origen.
• "cwd" (Directorio de trabajo actual) : a veces, es posible que necesite 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 en sí, lo que generalmente es sólido si la ruta del script es absoluta).
• "env" : Para pasar variables de entorno. Si bien nuestro servidor actual ubica serviceAccountKey.json en relación con su propia ruta, un patrón común en servidores más configurables es pasar rutas de credenciales u otras configuraciones mediante variables de entorno.

Flujo de interacción (Resumen):

1. El cliente inicia el servidor: el cliente MCP (que usa 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 query_firestore_collection o add_document_to_firestore según sea necesario.
4. El servidor responde: los resultados se envían al cliente a través de stdio .

Instrucciones específicas para Claude Desktop o Windsurf:

• Claude Desktop: Si usa Claude Desktop, consulte su documentación para saber cómo agregar y configurar servidores MCP personalizados. La estructura JSON anterior es un patrón común que podría adaptar.
• Windsurf: Si Windsurf es su orquestador y admite la administración de servidores MCP, tendrá su propio método para definir e iniciar estos servidores de herramientas externos. Deberá consultar la documentación de Windsurf para obtener más información, pero la información principal (comando, argumentos para ejecutar mcp_firebase_server.py ) será la misma.

Si su cliente no tiene un archivo de configuración/IU de administración de servidor MCP dedicado, pero puede ejecutar comandos de shell e interactuar a través de stdio, deberá iniciar programáticamente el script mcp_firebase_server.py y luego usar una biblioteca de cliente MCP (como la que está en mcp.client.stdio ) para comunicarse con él.

Desarrollo y pruebas

• Use mcp dev mcp_firebase_server.py para ejecutar el servidor con el Inspector de MCP. Esto le permite ver las herramientas detectadas y probarlas interactivamente.
• Asegúrese de que serviceAccountKey.json esté colocado correctamente O que la variable de entorno SERVICE_ACCOUNT_KEY_PATH esté configurada cuando un cliente MCP inicie el servidor.
• Verifique la salida de la consola del servidor para ver si hay 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. Determina su propia ubicación y cambia el directorio actual allí.
2. Localice y active un entorno virtual de Python llamado venv si existe en la raíz del proyecto.
3. Ejecute el script mcp_firebase_server.py usando el intérprete python (idealmente desde el venv activado).

Este script garantiza que el servidor MCP se ejecute en el entorno previsto. Recuerde configurarlo como ejecutable ( chmod +x run_server.sh ).