MCP Firebase Server

Conecta Modelos de Linguagem de Grande Porte ao Firebase Firestore e Storage através do Model Context Protocol.

Documentação

MCP Firebase Server (Model Context Protocol)

Este servidor implementa o Model Context Protocol (MCP) para atuar como uma ponte entre um Large Language Model (LLM) como o Claude e o Firebase (Firestore). Ele permite que o LLM leia e escreva em coleções do Firestore, expondo essas operações como "ferramentas" MCP.

Este servidor é construído usando o SDK Python oficial mcp.

Pré-requisitos

Python 3.7+ (preferencialmente 3.8+ para asynccontextmanager e recursos completos de type hinting usados pelo MCP)
Pip (instalador de pacotes Python) ou uv (recomendado pela documentação do MCP para gerenciamento de projetos)
Um projeto Firebase com Firestore habilitado.
Um arquivo JSON de chave de conta de serviço do Firebase.

Configuração

Clonar/Baixar: Certifique-se de ter o arquivo do servidor (mcp_firebase_server.py), requirements.txt, etc., em um diretório local.
Chave da Conta de Serviço:
- O servidor precisa de uma chave de conta de serviço do Firebase para autenticação.
- Opção 1 (Recomendada para Configuração do Cliente MCP): Defina a variável de ambiente SERVICE_ACCOUNT_KEY_PATH para o caminho absoluto do seu arquivo JSON da conta de serviço. Este é o método mais flexível quando o servidor é iniciado por um cliente MCP.
- Opção 2 (Alternativa): Se a variável de ambiente SERVICE_ACCOUNT_KEY_PATH não estiver definida, o servidor procurará um arquivo chamado serviceAccountKey.json em seu próprio diretório (o mesmo diretório de mcp_firebase_server.py). Se usar este método, renomeie seu arquivo de chave de acordo.
- Importante: Certifique-se de que seu arquivo de chave da conta de serviço (como for nomeado ou acessado) seja mantido em segurança e, idealmente, listado no seu .gitignore se houver uma cópia local no projeto.
Bucket de Armazenamento do Firebase (Opcional):
- Se você pretende usar funcionalidades do Firebase Storage com este servidor (atualmente nenhuma ferramenta o utiliza, mas pode ser adicionado), defina a variável de ambiente FIREBASE_STORAGE_BUCKET para o nome do bucket de armazenamento do seu projeto Firebase (por exemplo, your-project-id.appspot.com). O servidor lerá e imprimirá esse valor se estiver definido.

Criar um Ambiente Virtual (Recomendado): Usando venv:

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

Ou, se estiver usando uv (como sugerido pela documentação do MCP para novos projetos):

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

Instalar Dependências: Usando pip:
```
pip install -r requirements.txt
```
Ou, se estiver usando uv:
```
uv pip install -r requirements.txt
```
Isso instalará mcp[cli] e firebase-admin.

Executando o Servidor

Existem algumas maneiras de executar este servidor MCP:

Execução Direta (para transporte stdio via run_server.sh): Um script run_server.sh é fornecido para simplificar a inicialização do servidor. Este script ativa o ambiente virtual (se nomeado venv e presente na raiz do projeto) antes de executar o script Python.

Primeiro, torne o script executável:
```
chmod +x run_server.sh
```
Em seguida, execute o servidor usando o script:
```
./run_server.sh
```
É assim que um cliente MCP normalmente seria configurado para iniciar o servidor (veja a seção "Usando com o Claude" abaixo).
**Usando o MCP CLI para Desenvolvimento e Inspeção (mcp dev): O CLI mcp (instalado como parte de mcp[cli]) fornece um servidor de desenvolvimento e uma ferramenta de inspeção. Isso é altamente recomendado durante o desenvolvimento.
```
mcp dev mcp_firebase_server.py
```
Isso iniciará o servidor e frequentemente fornecerá uma interface web para inspecionar suas capacidades (ferramentas, recursos) e fazer chamadas de teste.

Ferramentas MCP Expostas

Este servidor, nomeado MCPFirebaseServer, expõe as seguintes ferramentas:

1. `mcp_firebase_query_firestore_collection`

Descrição (da docstring): Recupera documentos de uma coleção especificada do Firestore.
Argumentos:
- collection_name (string, obrigatório): O nome da coleção do Firestore a ser consultada.
- limit (inteiro, opcional, padrão: 50): O número máximo de documentos a retornar.
Retorna: Uma lista de documentos da coleção, ou uma mensagem de erro.

2. `mcp_firebase_add_document_to_firestore`

Descrição (da docstring): Adiciona um novo documento com um ID gerado automaticamente à coleção especificada do Firestore.
Argumentos:
- collection_name (string, obrigatório): O nome da coleção do Firestore onde o documento será adicionado.
- document_data (objeto/dicionário, obrigatório): Um dicionário representando o documento a ser adicionado.
Retorna: Um dicionário contendo o status de sucesso e o ID do novo documento, ou uma mensagem de erro.

3. `mcp_firebase_list_firestore_collections`

Descrição (da docstring): Lista todas as coleções de nível superior no banco de dados Firestore.
Argumentos:
- random_string (string, obrigatório): Um parâmetro dummy (pode ser qualquer string), pois esta ferramenta não recebe entrada significativa.
Retorna: Uma lista de dicionários, cada um contendo o 'id' de uma coleção, ou uma mensagem de erro.

4. `mcp_firebase_get_firestore_document`

Descrição (da docstring): Recupera um documento específico de uma coleção do Firestore pelo seu ID.
Argumentos:
- collection_name (string, obrigatório): O nome da coleção do Firestore.
- document_id (string, obrigatório): O ID do documento a ser recuperado.
Retorna: Um dicionário representando os dados do documento, ou uma mensagem de erro.

5. `mcp_firebase_list_document_subcollections`

Descrição (da docstring): Lista todas as subcoleções de um documento especificado no Firestore.
Argumentos:
- collection_name (string, obrigatório): O nome da coleção pai.
- document_id (string, obrigatório): O ID do documento cujas subcoleções devem ser listadas.
Retorna: Uma lista de dicionários, cada um contendo o 'id' de uma subcoleção, ou uma mensagem de erro.

6. `mcp_firebase_update_firestore_document`

Descrição (da docstring): Atualiza um documento existente em uma coleção especificada do Firestore.
Argumentos:
- collection_name (string, obrigatório): O nome da coleção do Firestore.
- document_id (string, obrigatório): O ID do documento a ser atualizado.
- update_data (objeto/dicionário, obrigatório): Um dicionário contendo os campos a serem atualizados.
Retorna: Um dicionário contendo o status de sucesso, ou uma mensagem de erro.

7. `mcp_firebase_query_firestore_collection_with_filter`

Descrição (da docstring): Recupera documentos de uma coleção especificada do Firestore, filtrando por valores de campo (somente igualdade ==).
Argumentos:
- collection_name (string, obrigatório): O nome da coleção do Firestore a ser consultada.
- filters (objeto/dicionário, obrigatório): Um dicionário onde as chaves são nomes de campos e os valores são os valores para filtrar (por exemplo, {"category": "electronics", "available": True}).
- limit (inteiro, opcional, padrão: 50): O número máximo de documentos a retornar.
Retorna: Uma lista de documentos da coleção que correspondem aos filtros, ou uma mensagem de erro.

Usando com o Claude (ou outros Clientes MCP)

Este MCP Firebase Server foi projetado para ser executado como um processo separado, normalmente iniciado por um aplicativo cliente MCP (como o Claude Desktop ou um aplicativo personalizado construído com uma plataforma como Windsurf que pode gerenciar servidores MCP). O cliente então se comunica com este servidor, geralmente via stdio (entrada/saída padrão) para servidores executados localmente.

Etapas Gerais de Integração:

Disponibilidade do Servidor: Certifique-se de que mcp_firebase_server.py e suas dependências (incluindo serviceAccountKey.json) estejam acessíveis no sistema onde o cliente MCP será executado ou possa iniciar processos.
Configuração do Cliente: O aplicativo cliente MCP precisa ser configurado para saber como iniciar seu MCPFirebaseServer. Essa configuração geralmente envolve especificar:
- Um comando a ser executado (por exemplo, python ou uv run python).
- Argumentos para esse comando (por exemplo, o caminho para mcp_firebase_server.py).
- Opcionalmente, quaisquer variáveis de ambiente que o servidor possa precisar (embora nosso servidor atual espere serviceAccountKey.json no mesmo diretório, uma variável de ambiente para o caminho da chave poderia ser uma alternativa).
Inicialização e Comunicação:
- Quando o cliente MCP precisar usar uma ferramenta fornecida por este servidor, ele iniciará mcp_firebase_server.py usando o comando configurado.
- O cliente e o servidor então se comunicam via protocolo MCP (por exemplo, via stdio). O cliente pode descobrir ferramentas disponíveis (como mcp_firebase_query_firestore_collection, mcp_firebase_add_document_to_firestore, etc.) e chamá-las.

Exemplo Conceitual de Configuração (para um Cliente MCP como o Claude Desktop):

Muitos aplicativos clientes compatíveis com MCP (como o Claude Desktop, conforme referenciado na documentação do MCP) usam um arquivo de configuração (frequentemente JSON) para definir como iniciar e gerenciar servidores MCP. Embora o formato exato possa variar por cliente, o princípio é semelhante.

Abaixo está um exemplo conceitual baseado em padrões vistos na documentação do MCP. Você precisaria adaptar isso ao mecanismo de configuração específico do seu cliente MCP escolhido (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" 
      }
    }
  }
}

Pontos-chave para a configuração:

"command": O executável a ser executado (por exemplo, python). Certifique-se de que esteja no PATH do sistema ou forneça o caminho completo para o interpretador Python.
"args": Uma lista de argumentos. O primeiro argumento é tipicamente o script a ser executado. É crucial usar o caminho completo e absoluto para mcp_firebase_server.py para garantir que o cliente possa encontrá-lo, independentemente de onde o cliente em si foi iniciado.
"cwd" (Diretório de Trabalho Atual): Às vezes, você pode precisar especificar o diretório de trabalho para o processo do servidor, especialmente se ele depender de caminhos relativos para outros arquivos (embora nosso caminho serviceAccountKey.json seja relativo ao próprio script, o que é geralmente robusto se o caminho do script for absoluto).
"env": Para passar variáveis de ambiente. Embora nosso servidor atual localize serviceAccountKey.json relativo ao seu próprio caminho, um padrão comum para servidores mais configuráveis é passar caminhos de credenciais ou outras configurações via variáveis de ambiente. O SERVICE_ACCOUNT_KEY_PATH é crucial para autenticação. O FIREBASE_STORAGE_BUCKET é opcional e atualmente não usado pelas ferramentas fornecidas, mas pode ser relevante se ferramentas relacionadas a armazenamento forem adicionadas posteriormente.

Fluxo de Interação (Recapitulação):

Cliente Inicia o Servidor: O cliente MCP (usando a configuração acima) inicia mcp_firebase_server.py.
Servidor Inicializa: Nosso servidor tenta se conectar ao Firebase.
Descoberta e Chamadas de Ferramentas: O cliente descobre e chama ferramentas como mcp_firebase_query_firestore_collection ou mcp_firebase_add_document_to_firestore etc., conforme necessário.
Servidor Responde: Os resultados são enviados de volta ao cliente via stdio.

Instruções Específicas para Claude Desktop ou Windsurf:

Claude Desktop: Se você estiver usando o Claude Desktop, consulte sua documentação sobre como adicionar e configurar servidores MCP personalizados. A estrutura JSON acima é um padrão comum que você pode adaptar.
Windsurf: Se o Windsurf for seu orquestrador e ele suportar gerenciamento de servidores MCP, ele terá seu próprio método para definir e iniciar esses servidores de ferramentas externos. Você precisaria consultar a documentação do Windsurf para os detalhes, mas as informações principais (comando, argumentos para executar mcp_firebase_server.py) serão as mesmas.

Se seu cliente não tiver uma interface/arquivo de configuração dedicado para gerenciamento de servidores MCP, mas puder executar comandos de shell e interagir via stdio, você iniciaria programaticamente o script mcp_firebase_server.py e então usaria uma biblioteca de cliente MCP (como a do mcp.client.stdio) para se comunicar com ele.

Desenvolvimento e Testes

Use mcp dev mcp_firebase_server.py para executar o servidor com o MCP Inspector. Isso permite que você veja as ferramentas descobertas e as teste interativamente.
Certifique-se de que serviceAccountKey.json esteja corretamente colocado OU que a variável de ambiente SERVICE_ACCOUNT_KEY_PATH esteja definida quando o servidor for iniciado por um cliente MCP.
Verifique a saída do console do servidor para mensagens de inicialização do Firebase e quaisquer erros de tempo de execução.

O Script run_server.sh: O script run_server.sh na raiz do projeto foi projetado para:

Determinar sua própria localização e alterar o diretório atual para lá.
Localizar e ativar um ambiente virtual Python chamado venv se ele existir na raiz do projeto.
Executar o script mcp_firebase_server.py usando o interpretador python (idealmente do venv ativado).

Este script garante que o servidor MCP seja executado em seu ambiente pretendido. Lembre-se de torná-lo executável (chmod +x run_server.sh).

MCP Firebase Server

Documentação