mcp-firebird

English · Italiano · Español · Deutsch

MCP Firebird

Pergunte ao seu assistente de IA por que uma consulta está lenta e obtenha uma resposta que vale a pena agir.

Um servidor Model Context Protocol para Firebird 2.5 a 5.0. Aponte-o para um banco de dados e seu assistente poderá ler os planos de acesso reais, dizer qual índice está faltando e quais quatro são peso morto, auditar a saúde de uma tabela e encontrar a transação que está segurando a coleta de lixo desde terça-feira.

As respostas vêm do seu banco de dados, não de um artigo: o servidor pede ao Firebird o plano (SET PLANONLY), lê as tabelas de monitoramento (MON$) e conta quantos valores distintos uma coluna realmente possui antes de afirmar que um índice nela valeria a pena. Cada resposta chega como Finding (o que está errado), SQL (a instrução que corrige) e Verify (como verificar se funcionou). Nada é gravado no seu banco de dados: o servidor anexa somente leitura, e o SQL que ele entrega é seu para executar, se e quando você decidir.

• Transporte: stdio (JSON-RPC 2.0, MCP 2025-03-26) · Identidade do servidor: mcp-firebird v0.5.0
• Mecanismos: Firebird 2.5, 3.0, 4.0, 5.0 — detecção de capacidade em tempo de execução
• Grátis em seus próprios bancos de dados, em qualquer escala, sem chave e sem expiração. Uma licença é necessária apenas para repassar o software a outra pessoa (detalhes)

---

Início rápido

Cinco minutos, quatro passos. Windows x64.

1. Obtenha o servidor. Baixe o último lançamento e descompacte-o, por exemplo, em C:\Tools\MCPFirebird. Compilando a partir do código-fonte: Compilação e testes.

2. Diga qual banco de dados. Copie .env.example ao lado do exe como .env e preencha quatro linhas:

firebird.database=C:\data\MYAPP.FDB
firebird.user=SYSDBA
firebird.password=masterkey
firebird.client_lib=C:\Program Files\Firebird\Firebird_5_0\fbclient.dll

O zip deliberadamente não inclui fbclient.dll: o correto é a biblioteca cliente do seu próprio servidor.

3. Registre-o com seu agente de IA. É um servidor stdio — o agente inicia o exe sozinho, então toda a instalação é um único comando. Claude Code:

claude mcp add firebird -- "C:\Tools\MCPFirebird\MCPFirebird.exe"

Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json), Cursor (.cursor/mcp.json), VS Code (.vscode/mcp.json) todos aceitam o mesmo formato:

{ "mcpServers": { "firebird": { "command": "C:\\Tools\\MCPFirebird\\MCPFirebird.exe" } } }

Gemini CLI e OpenCode diferem ligeiramente — trechos para cada cliente estão em Setup.

4. Pergunte algo.

Você: A qual versão do Firebird estou conectado e quais tabelas estão no banco de dados?

Você: Esta consulta está lenta, por quê? SELECT * FROM CUSTOMERS WHERE CITY = 'Rome'

Você: Sugira um índice que corrija isso.

Essa é toda a configuração. Se o cliente listar o servidor, mas não mostrar ferramentas, consulte Solução de problemas, no final desta página.

---

O que você pode perguntar

Pergunta	O que acontece
"Documente a tabela CUSTOMERS"	Documentos Markdown: colunas, PK, índices, gatilhos. Deixe a tabela de fora e você obtém todo o banco de dados, procedimentos e pacotes incluídos
"Por que esta consulta está lenta?"	O plano de acesso, os scans NATURAL e ordenações externas nele, o plano explicado pelo mecanismo no 3.0+, e quanto a consulta realmente custou quando executada uma vez
"Sugira um índice"	O remédio mais barato que explica o plano — atualize estatísticas obsoletas, ative um índice inativo ou crie um — e "nenhum índice, o scan está correto aqui" com os números, quando essa for a resposta
"Quais índices posso descartar?"	Duplicados, prefixos redundantes, índices inativos e de baixa seletividade, com o DROP INDEX e uma etapa de verificação
"Audite esta tabela"	Chave primária ausente, excesso de indexação, estatísticas obsoletas
"Continue otimizando até que esta consulta pare de fazer scan NATURAL"	O loop de meta: ele muda, re-mede no banco de dados e para quando a medição diz que a meta foi atingida — não quando o assistente acha que sim
"Ela arrasta todas as tardes e ninguém mudou nada"	Classifica o sintoma antes de tocar em uma ferramenta, então amostra MON$ em uma janela para mostrar o que se acumula
"Quem está conectado e o que estão executando?"	Cada anexo com seu usuário, endereço e processo, a instrução que está executando agora e há quanto tempo
"Faça backup do banco de dados"	Executa gbak em segundo plano e restaura o que gravou em um banco de dados temporário, então a resposta é "este backup restaura", não "um arquivo existe"

Cada análise também termina com o que ela não descarta: um plano não pode ver contenção, e um instantâneo não pode ver acumulação.

→ Exemplos práticos, saída de ferramenta verbatim, um ciclo completo em employee.fdb

---

As ferramentas

Treze ferramentas, três prompts, um recurso. Referência completa — argumentos, o que cada uma decide, as formas brutas de tools/call — em docs/tools.md.

fb_info · fb_list_tables · fb_generate_documentation · fb_analyze_query · fb_suggest_indexes · fb_suggest_index_drops · fb_audit_table · fb_evaluate_goal · fb_monitor_transactions · fb_sample_activity · fb_monitor_attachments · fb_backup_start · fb_backup_status

fb_backup_start retorna antes do backup — consulte fb_backup_status. Ele precisa de firebird.backup_dir definido no .env, gbak.exe ao lado do seu fbclient.dll e espaço nesse disco para uma segunda cópia do banco de dados enquanto a restauração de verificação é executada.

Prompts: optimization_goal (iterar até atingir) · health_check · classify_problem. Recurso: firebird://schema.

Nove outras ferramentas aparecem em tools/list e pertencem à edição Enterprise: seu assistente pode vê-las e dizer o que faria com elas.

---

Edições

Usar em seus próprios bancos de dados é grátis e continua grátis. Sem teste, sem expiração, sem chave de licença, sem contagem de assentos. Consultores: é sua ferramenta, use-a nos bancos de dados de seus clientes e cobre pelo seu tempo. A única coisa que precisa de licença é deixar uma cópia sair de suas mãos — redistribuí-la, incorporá-la em um produto que você vende ou oferecê-la como serviço.

Uma edição Enterprise paga separada assume onde uma conexão SQL termina: firebird.conf, a RAM e CPUs da máquina, firebird.log, a API Trace, o relatório de armazenamento físico. Você a quer quando o esquema está em ordem e o banco de dados ainda está lento.

→ Edições, licenciamento e os casos práticos · d.teti@bittime.it

---

Documentação

Setup	Pré-requisitos, a referência .env, --env <dir>, vários bancos de dados de uma única compilação, trechos por cliente, teste de fumaça manual
Exemplos práticos	As conversas, saída de ferramenta verbatim, um ciclo de otimização
Referência de ferramentas	Todas as dez ferramentas, como o consultor de índices decide, prompts, recursos, ferramentas Enterprise
Edições e licenciamento	O que é grátis, o que precisa de licença, o que Enterprise adiciona
Compilação e testes	Compilação Delphi, a matriz de testes 2.5→5.0, como usa mcp-server-delphi
Catálogo de problemas	Cada problema detectado, o fixture que o provoca, o marco

---

Solução de problemas

Sintoma	Causa provável / correção
Cliente mostra o servidor, mas sem ferramentas	.env ausente ou DB inacessível: o servidor inicia, mas as ferramentas falham na conexão. Teste com o teste de fumaça manual.
Your user name and password are not defined (SQLSTATE 28000)	Credenciais erradas, ou um zip-kit do Firebird que não inclui um SYSDBA utilizável (veja Compilação e testes).
Ferramentas de análise retornam vazio / sem scan NATURAL em um DB remoto	Garanta que firebird.host seja o host real (o analisador de plano usa o host configurado).
fbclient.dll não encontrado / bitness errado	Defina firebird.client_lib para um fbclient.dll Win64; um cliente 5.0 funciona contra 2.5-5.0.
stdout tem ruído não-JSON	O registro deve ir apenas para arquivo: mantenha logger.config.file=loggerpro.stdio.json.
Porta 3050 já em uso por outro Firebird	Use uma porta distinta (o harness de teste coloca FB 2.5 na 3070 por esse motivo).

---

Segurança e compatibilidade

• Somente leitura, e não por sistema de honra. O servidor abre suas transações somente leitura, então um INSERT, UPDATE, DELETE ou DDL é recusado pelo Firebird, não por uma verificação nossa que poderia estar errada sobre o que uma instrução faz. Isso importa porque três ferramentas executam SQL que chega como texto do chamador — fb_analyze_query mede o SELECT que analisa, fb_suggest_indexes mede aquele sobre o qual aconselha e fb_evaluate_goal cronometra um. Todas as três também recusam qualquer coisa que não seja um SELECT simples antes de executá-lo e recusam executar uma instrução cujos parâmetros ninguém vinculou; a transação somente leitura é o que segura se uma recusa estiver errada. O SQL que um consultor entrega é seu para executar, quando e se você decidir. Ferramentas que aplicam uma mudança por conta própria estão planejadas e, quando chegarem, ficarão desativadas a menos que você as ative.
• Entre versões. A detecção de capacidade adapta o uso de recursos (tabelas MON$, planos explicados, BOOLEAN, INT128, fusos horários, trabalhadores paralelos) ao mecanismo conectado; validado em FB 2.5 / 3.0 / 4.0 / 5.0.
• Banco de dados único configurado por instância do servidor (execute várias instâncias para vários DBs).

---

Licença

A partir da v0.2.0, licenciado sob a PolyForm Internal Use License 1.0.0: grátis em seus próprios bancos de dados, em qualquer escala, e uma licença é necessária apenas para repassar o software a outra pessoa. v0.1.0 e anteriores foram lançados sob Apache-2.0 e permanecem assim para todos que os receberam. Veja Edições e licenciamento e NOTICE.

Construído com mcp-server-delphi, que por sua vez se apoia em DelphiMVCFramework. Este servidor é um exemplo completo e real do que você pode construir com eles: se você está escrevendo seu próprio servidor MCP em Delphi, comece por aí.