MCP Firebird

Um servidor MCP para bancos de dados Firebird SQL, permitindo que LLMs acessem, analisem e manipulem conteúdo de banco de dados de forma segura.

GitHub

Experimente este MCPPatrocinado

Documentação

MCP Firebird

Implementação do MCP (Model Context Protocol) da Anthropic para bancos de dados Firebird.

Exemplo de Uso

https://github.com/user-attachments/assets/e68e873f-f87b-4afd-874f-157086e223af

O que é o MCP Firebird?

O MCP Firebird é um servidor que implementa o Model Context Protocol (MCP) da Anthropic para bancos de dados Firebird SQL. Ele permite que Modelos de Linguagem de Grande Porte (LLMs) como o Claude acessem, analisem e manipulem dados em bancos de dados Firebird de forma segura e controlada.

🚀 Novidades no MCP 2.7+ (Desempenho e Segurança)

Este servidor foi atualizado para suportar os padrões empresariais mais recentes no ecossistema MCP:

⚡ Pool de Conexões (Latência Zero): Consultas repetitivas ao banco de dados agora usam conexões persistentes em memória, ignorando completamente a sobrecarga de handshake e executando quase instantaneamente.
🎯 Eventos Proativos (Triggers): Integração nativa com o POST_EVENT do Firebird. O servidor escuta eventos do banco de dados em tempo real e notifica proativamente o cliente de IA (ex.: Claude/n8n) sem exigir polling contínuo.
- Exemplo Rápido: Peça ao seu agente para subscribe_to_event com NEW_ORDER. Quando o Firebird executar POST_EVENT 'NEW_ORDER', seu agente será notificado instantaneamente! Leia o guia detalhado e exemplos.
🛡️ Autorização Gerenciada Empresarial (EMA): Não quer expor sua senha real do banco de dados (SYSDBA) ao cliente LLM? Ative a EMA para exigir um --api-key nas conexões de entrada. O servidor intercepta esse token e injeta a senha real de forma segura nos bastidores.
- Exemplo Rápido: Inicie o servidor com --password "real_password" --api-key "my-secure-token". O cliente remoto se conecta usando Authorization: Bearer my-secure-token. A senha do banco de dados nunca sai do servidor! Leia o guia detalhado em Segurança.
🌊 Streaming Bidirecional (Streamable HTTP / SSE): Perfeito para n8n ou implantações remotas. Fornece streaming de eventos em tempo real e sessões com estado via HTTP.
- Exemplo Rápido: Inicie o servidor com TRANSPORT_TYPE=sse SSE_PORT=3003. Configure seu cliente (como n8n) para conectar-se a http://YOUR_SERVER:3003/mcp. Leia o guia detalhado.

🏗️ Modos de Transporte e Arquitetura

O MCP Firebird suporta múltiplas arquiteturas de implantação. Recomendamos fortemente o uso de Streamable HTTP (SSE) para implantações modernas, empresariais ou remotas.

1. [RECOMENDADO] Transporte Moderno (Streamable HTTP / SSE)

Ideal para conectar n8n, plataformas em nuvem, agentes remotos ou ferramentas que não residem na mesma máquina que seu banco de dados.

Instalação:

npm install -g mcp-firebird

Execute o Servidor: Configure suas variáveis de ambiente (ou arquivo .env):

export TRANSPORT_TYPE=sse
export SSE_PORT=3003

# Real database credentials protected on the server side:
export FIREBIRD_PASSWORD=masterkey 
# Enable EMA to protect external access:
export FIREBIRD_API_KEY=my_secret_token_123

mcp-firebird --database /path/to/database.fdb --user SYSDBA

Conexão do Cliente: Seu cliente de IA (ex.: MCP Inspector, n8n) conecta-se a http://localhost:3003 e, graças à EMA, precisa apenas fornecer a CHAVE DA API em vez da senha real do banco de dados.

2. [LOCAL / LEGADO] Transporte Padrão (STDIO)

Este é o método clássico recomendado apenas para uso pessoal na mesma máquina (ex.: Claude Desktop). O Claude inicia seu próprio subprocesso MCP Firebird em segundo plano.

Principais Recursos

Consultas SQL: Execute consultas SQL em bancos de dados Firebird
Análise de Esquema: Obtenha informações detalhadas sobre tabelas, colunas e relacionamentos
Metadados do Banco de Dados: Inspecione triggers, procedimentos armazenados, funções e pacotes com código-fonte
Análise de Desempenho: Analise o desempenho de consultas e sugira otimizações
Segurança: Inclui validação de consultas SQL, EMA e Pool de Conexões.
Suporte a Dois Drivers: Escolha entre instalação simples (padrão) ou driver nativo com suporte a criptografia de fio.

🔒 Suporte a Criptografia de Fio

O MCP Firebird suporta duas opções de driver:

Driver	Instalação	Criptografia de Fio	Caso de Uso
JavaScript Puro (padrão)	✅ Simples (`npx`)	❌ Não	Maioria dos usuários, configuração rápida
Driver Nativo (opcional)	⚠️ Complexo (requer ferramentas de compilação)	✅ Sim	Empresarial, segurança necessária

Início Rápido (Padrão - Sem Criptografia de Fio)

npx -y mcp-firebird --database=/path/to/database.fdb

Avançado (Com Suporte a Criptografia de Fio)

⚠️ CRÍTICO: npx NÃO funciona com o driver nativo. Você DEVE instalar globalmente.

⚠️ IMPORTANTE: A criptografia de fio deve ser configurada no servidor Firebird (firebird.conf), não no cliente.

Configuração do Servidor (necessária primeiro):

# In firebird.conf on the server
WireCrypt = Required  # or Enabled

Instalação do Cliente (DEVE ser global):

# Step 1: Install build tools
# Windows: Visual Studio Build Tools (https://visualstudio.microsoft.com/downloads/)
# Linux: sudo apt-get install build-essential python3 firebird-dev
# macOS: xcode-select --install && brew install firebird

# Step 2: Install MCP Firebird globally
npm install -g mcp-firebird

# Step 3: Install native driver globally
npm install -g node-firebird-driver-native

# Step 4: Run directly (WITHOUT npx)
mcp-firebird --use-native-driver \
  --database=/path/to/database.fdb \
  --host=localhost \
  --user=SYSDBA \
  --password=masterkey

Por que não npx? Quando o npx executa um pacote de seu cache temporário, ele não consegue acessar módulos instalados globalmente como node-firebird-driver-native. Ambos os pacotes devem ser instalados globalmente no mesmo local.

📚 Para instruções detalhadas de instalação, veja:

Guia de Instalação do Driver Nativo - Passo a passo para Windows/Linux/macOS
Guia de Criptografia de Fio
Guia de Instalação Avançada

Instalação Manual

Versão Estável

# Global installation
npm install -g mcp-firebird

# Run the server
npx -y mcp-firebird --database /path/to/database.fdb

Recursos Estáveis (v2.2.3):

🐛 CORRIGIDO: Bug de parsing JSON SSE - resolve erros "Invalid message: [object Object]"
✨ Suporte a transporte Streamable HTTP (MCP 2025-03-26)
🔄 Servidor unificado com detecção automática de protocolo
📊 Gerenciamento e monitoramento aprimorados de sessão
🛠️ Integração moderna com MCP SDK (v1.13.2)
🔧 Tratamento de erros e registro aprimorados
🧪 Suíte de testes abrangente com 9+ testes para funcionalidade SSE

Versão Alpha (Recursos Mais Recentes)

# Install alpha version with latest features
npm install -g mcp-firebird@alpha

# Or use specific alpha version
npm install -g mcp-firebird@2.4.0-alpha.0

Recursos Alpha (v2.4.0-alpha.0):

NOVO: Pronto para o próximo ciclo de desenvolvimento
✨ Todos os recursos estáveis da v2.2.3 incluídos
🔄 Servidor unificado com detecção automática de protocolo
📊 Gerenciamento e monitoramento aprimorados de sessão
🛠️ Integração moderna com MCP SDK (v1.13.2)
🔧 Tratamento de erros e registro aprimorados
🧪 Suíte de testes abrangente com 9+ testes para funcionalidade SSE
📚 Documentação aprimorada com guias de solução de problemas

Nota: A correção do bug de parsing JSON SSE agora está disponível na versão estável v2.2.3

Para integração com VSCode e GitHub Copilot, veja Integração VSCode.

Uso Básico

Com Claude Desktop

Edite a configuração do Claude Desktop:

code $env:AppData\Claude\claude_desktop_config.json  # Windows
code ~/Library/Application\ Support/Claude/claude_desktop_config.json  # macOS

Adicione a configuração do MCP Firebird:

{
  "mcpServers": {
    "mcp-firebird": {
      "command": "npx",
      "args": [
        "mcp-firebird",
        "--host",
        "localhost",
        "--port",
        "3050",
        "--database",
        "C:\\path\\to\\database.fdb",
        "--user",
        "SYSDBA",
        "--password",
        "masterkey"
      ],
      "type": "stdio"
    }
  }
}

Reinicie o Claude Desktop

Configuração de Transporte

O MCP Firebird suporta múltiplos protocolos de transporte para atender diferentes necessidades de clientes e cenários de implantação.

Transporte STDIO (Padrão)

O transporte STDIO é o método padrão para integração com Claude Desktop:

{
  "mcpServers": {
    "mcp-firebird": {
      "command": "npx",
      "args": [
        "mcp-firebird",
        "--database", "C:\\path\\to\\database.fdb",
        "--user", "SYSDBA",
        "--password", "masterkey"
      ],
      "type": "stdio"
    }
  }
}

Transporte SSE (Server-Sent Events)

O transporte SSE permite que o servidor execute como um serviço web, útil para aplicações web e acesso remoto:

Configuração Básica SSE

# Start SSE server on default port 3003
npx mcp-firebird --transport-type sse --database /path/to/database.fdb

# Custom port and full configuration
npx mcp-firebird \
  --transport-type sse \
  --sse-port 3003 \
  --database /path/to/database.fdb \
  --host localhost \
  --port 3050 \
  --user SYSDBA \
  --password masterkey

Variáveis de Ambiente para SSE

# Set environment variables
export TRANSPORT_TYPE=sse
export SSE_PORT=3003
export DB_HOST=localhost
export DB_PORT=3050
export DB_DATABASE=/path/to/database.fdb
export DB_USER=SYSDBA
export DB_PASSWORD=masterkey

# Start server
npx mcp-firebird

Conexão do Cliente SSE

Uma vez que o servidor SSE está em execução, os clientes podem se conectar a:

Endpoint SSE: http://localhost:3003/sse
Endpoint de Mensagens: http://localhost:3003/messages
Verificação de Saúde: http://localhost:3003/health

Transporte Streamable HTTP (Moderno)

O protocolo MCP mais recente que suporta comunicação bidirecional:

# Start with Streamable HTTP
npx mcp-firebird --transport-type http --http-port 3003 --database /path/to/database.fdb

Transporte Unificado (Recomendado)

Suporta ambos os protocolos SSE e Streamable HTTP simultaneamente com detecção automática:

# Start unified server (supports both SSE and Streamable HTTP)
npx mcp-firebird --transport-type unified --http-port 3003 --database /path/to/database.fdb

Endpoints do Servidor Unificado

SSE (Legado): http://localhost:3003/sse
Streamable HTTP (Moderno): http://localhost:3003/mcp
Auto-Detecção: http://localhost:3003/mcp-auto
Verificação de Saúde: http://localhost:3003/health

Exemplos de Configuração

Configuração de Desenvolvimento (SSE)

npx mcp-firebird \
  --transport-type sse \
  --sse-port 3003 \
  --database ./dev-database.fdb \
  --user SYSDBA \
  --password masterkey

Configuração de Produção (Unificado)

npx mcp-firebird \
  --transport-type unified \
  --http-port 3003 \
  --database /var/lib/firebird/production.fdb \
  --host db-server \
  --port 3050 \
  --user APP_USER \
  --password $DB_PASSWORD

Docker com SSE

docker run -d \
  --name mcp-firebird \
  -p 3003:3003 \
  -e TRANSPORT_TYPE=sse \
  -e SSE_PORT=3003 \
  -e DB_DATABASE=/data/database.fdb \
  -v /path/to/database:/data \
  purodelhi/mcp-firebird:latest

Configuração SSE Avançada

Gerenciamento de Sessão

Configure tempos limite e limites de sessão:

# Environment variables for session management
export SSE_SESSION_TIMEOUT_MS=1800000    # 30 minutes
export MAX_SESSIONS=1000                 # Maximum concurrent sessions
export SESSION_CLEANUP_INTERVAL_MS=60000 # Cleanup every minute

npx mcp-firebird --transport-type sse

Configuração CORS

Para aplicações de navegador, restrinja o acesso a uma ou mais origens separadas por vírgula. O padrão é * com credenciais de navegador desabilitadas, para que clientes MCP STDIO e Bearer-token existentes permaneçam compatíveis:

# Allow specific browser origins
export MCP_ALLOWED_ORIGIN="https://myapp.com,https://localhost:3000"

npx mcp-firebird --transport-type sse

A versão estável 2.11.0 inclui todas as melhorias de segurança e compatibilidade das versões 2.11.0-alpha.1 a alpha.4, incluindo configuração JSON inline e a correção de parsing EXTRACT/SUBSTRING/TRIM. Instale com npm install -g mcp-firebird@latest, ou fixe mcp-firebird@2.11.0. Políticas existentes contendo configurações anteriormente dormentes agora as aplicam; revise o guia de migração.

Escritas SQL brutas são desabilitadas por padrão. 2.11.0 preserva o switch histórico ALLOW_RAW_SQL=true para escritas, incluindo DDL, sem exigir novos flags. Restrições explicitamente configuradas de operação/tabela/linha/mascaramento/papel e sql.allowDDL=false nunca são ignoradas por esse switch. Veja o guia de segurança para controles opt-in e o formato estruturado de filtro get-table-data.

Arquivos de segurança personalizados podem ser carregados com --security-config /absolute/path/security-config.json ou a variável de ambiente FIREBIRD_SECURITY_CONFIG. SECURITY_CONFIG e SECURITY_CONFIG_PATH são aliases de fallback, nessa ordem; a opção de CLI tem precedência sobre variáveis de ambiente. Use um objeto JSON como {"security":{"allowedTables":["EMPLOYEES"],"allowedOperations":["SELECT"],"maxRows":100}}. Arquivos CommonJS confiáveis também são suportados. Reinicie após alterar a política e verifique Loaded security configuration from .... A partir de 2.11.0-alpha.2, arquivos selecionados inválidos ou ausentes interrompem a inicialização em vez de aplicar padrões silenciosamente. Veja o guia de segurança.

A partir de 2.11.0-alpha.1, defina FIREBIRD_SECURITY_JSON para essa mesma string JSON para configurar segurança sem arquivo. Opções SQL também são suportadas. Em 2.11.0-alpha.3, restrições avançadas são opt-in: sem cotas de recursos implícitas, prazos, negação de catálogo ou novas restrições de rotina. Defina apenas os controles que você precisa; por exemplo, {"security":{"maxRows":100}} ativa apenas esse limite de linhas. Políticas explícitas são aplicadas, incluindo opções que versões mais antigas não aplicavam. Caminhos de arquivo têm precedência. Apenas um administrador/launcher confiável pode definir a variável; clientes HTTP/SSE não podem alterá-la. JSON inline é limitado a 64 KiB (UTF-8), validado sem executar código, e não é registrado pelo loader. Políticas inválidas rejeitam a inicialização. Desdefina a variável para desabilitar essa fonte e reinicie após alterações. Revise o aviso de migração, exemplos de configuração e revisão de implementação.

Suporte SSL/TLS

Para implantações de produção, use um proxy reverso como nginx:

server {
    listen 443 ssl;
    server_name mcp-firebird.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3003;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Solução de Problemas

Problemas de Conexão com Firebird

Incompatibilidade de Criptografia de Fio (Firebird 3.0+) ⚠️ CRÍTICO

Erro: Incompatible wire encryption levels requested on client and server

IMPORTANTE: A biblioteca node-firebird NÃO suporta criptografia de fio do Firebird 3.0+. O parâmetro --wire-crypt NÃO funciona.

ÚNICA Solução: Você DEVE desabilitar a criptografia de fio no servidor Firebird:

Para Firebird 3.0, adicione a firebird.conf:
```
WireCrypt = Disabled
AuthServer = Srp, Legacy_Auth
```
Para Firebird 4.0+, adicione a firebird.conf:
```
WireCrypt = Disabled
AuthServer = Srp256, Srp, Legacy_Auth
```
Para Firebird 5.0 Docker:
```
environment:
  FIREBIRD_CONF_WireCrypt: Disabled
  FIREBIRD_CONF_AuthServer: Srp256, Srp
```
Se você não puder alterar a configuração do servidor, veja Limitação de Criptografia de Fio para alternativas.
Problemas de Caminho do Banco de Dados no Linux/Unix

Problema: Strings de conexão remotas ou caminhos Unix não funcionando

Solução: Isso foi corrigido na v2.4.0-alpha.1+. Os seguintes caminhos agora funcionam corretamente:
- Remoto: server:/path/to/database.fdb
- Unix absoluto: /var/lib/firebird/database.fdb
- Baseado em IP: 192.168.1.100:/data/db.fdb
Erro de I/O com Caminhos de Maiúsculas/Minúsculas Mistas no Windows

Erro: I/O error during CreateFile (open) operation

Problema: Caminho do banco de dados com maiúsculas/minúsculas mistas (ex.: C:\MyData\database.fdb) causa erros

Soluções Alternativas:
- Use caminhos totalmente em maiúsculas: C:\MYDATA\DATABASE.FDB
- Use barras normais: C:/MyData/database.fdb
- Veja Documentação de Correção de Criptografia de Fio para mais detalhes

Problemas de Conexão SSE

Conexão Recusada

# Check if server is running
curl http://localhost:3003/health

# Check port availability
netstat -an | grep 3003

Tempo Limite de Sessão

# Increase session timeout
export SSE_SESSION_TIMEOUT_MS=3600000  # 1 hour

Erros CORS

# Allow all origins (development only)
export CORS_ORIGIN="*"

Problemas de Memória

# Reduce max sessions
export MAX_SESSIONS=100

# Enable more frequent cleanup
export SESSION_CLEANUP_INTERVAL_MS=30000

Problemas de Parsing JSON (Corrigido na v2.3.0-alpha.1+)

# If experiencing "Invalid message: [object Object]" errors,
# upgrade to the latest alpha version:
npm install mcp-firebird@alpha

# Or use the latest alpha directly:
npx mcp-firebird@alpha --transport-type sse

Nota: Versões anteriores à 2.3.0-alpha.1 tinham um bug em que requisições POST ao endpoint /messages falhavam ao analisar o corpo JSON corretamente. Isso foi corrigido com um melhor tratamento de middleware para ambos os tipos de conteúdo application/json e text/plain.

Monitoramento e Registros

# Enable debug logging
export LOG_LEVEL=debug

# Monitor server health
curl http://localhost:3003/health | jq

# Check active sessions
curl http://localhost:3003/health | jq '.sessions'

Documentação

Para informações mais detalhadas, consulte os seguintes documentos:

Primeiros Passos

Instalação Completa
Opções de Configuração
Ferramentas Disponíveis
Ferramentas de Metadados do Banco de Dados - Inspecione triggers, procedures, funções e pacotes
Referência de Recursos, Ferramentas e Prompts - Guia completo de todas as capacidades do MCP

Protocolos de Transporte

Configuração de Transporte

Guias de Integração

Tópicos Avançados

Segurança
Solução de Problemas
Correção de Criptografia de Transmissão - Compatibilidade com Firebird 3.0+ e correção de caminho no Linux

Exemplos e Casos de Uso

Casos de Uso e Exemplos

Apoie o Projeto

Doações

Se você acha o MCP Firebird útil para seu trabalho ou projetos, considere apoiar seu desenvolvimento por meio de uma doação. Suas contribuições ajudam a manter e melhorar esta ferramenta.

GitHub Sponsors: Patrocinar @PuroDelphi
PayPal: Doar via PayPal

Contrate Nossos Agentes de IA

Outra ótima maneira de apoiar este projeto é contratando nossos agentes de IA através da Asistentes Autónomos. Oferecemos assistentes de IA especializados para diversas necessidades empresariais, ajudando você a automatizar tarefas e melhorar a produtividade.

Suporte Prioritário

⭐ Doadores, patrocinadores e clientes recebem suporte prioritário e assistência com problemas, solicitações de recursos e orientação de implementação. Embora nos esforcemos para ajudar todos os usuários, aqueles que apoiam o projeto financeiramente receberão tempos de resposta mais rápidos e assistência dedicada.

Seu apoio é muito apreciado e ajuda a garantir o desenvolvimento contínuo do MCP Firebird!

Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.