mcp-firebird
A Model Context Protocol server for Firebird 2.5 – 5.0, written in Delphi with the official `fbclient` driver. It lets an AI assistant document schemas, analyze query plans, advise on indexes (which to add and which to drop), audit schema health, and drive goal-based optimization. Read-only by default.
Documentación
English · Italiano · Español · Deutsch
MCP Firebird
Pregúntale a tu asistente de IA por qué una consulta es lenta y obtén una respuesta que vale la pena aplicar.
Un servidor de Model Context Protocol para Firebird 2.5 a 5.0. Apúntalo a una base de datos y tu asistente podrá leer los planes de acceso reales, decirte qué índice falta y cuáles cuatro son peso muerto, auditar la salud de una tabla y encontrar la transacción que ha estado bloqueando la recolección de basura desde el martes.
Las respuestas salen de tu base de datos, no de un artículo: el servidor le pide a Firebird el plan (SET PLANONLY), lee las tablas de monitoreo (MON$) y cuenta cuántos valores distintos tiene realmente una columna antes de afirmar que un índice sobre ella valdría la pena. Cada respuesta llega como Hallazgo (qué está mal), SQL (la sentencia que lo arregla) y Verificar (cómo comprobar que funcionó). No se escribe nada en tu base de datos: el servidor se conecta en modo solo lectura, y el SQL que te entrega es tuyo para ejecutarlo, si y cuando decidas hacerlo.
- Transporte: stdio (JSON-RPC 2.0, MCP
2025-03-26) · Identidad del servidor:mcp-firebirdv0.5.0 - Motores: Firebird 2.5, 3.0, 4.0, 5.0 — detección de capacidades en tiempo de ejecución
- Gratis en tus propias bases de datos, a cualquier escala, sin clave y sin caducidad. Se necesita una licencia solo para pasar el software a otra persona (detalles)
Inicio rápido
Cinco minutos, cuatro pasos. Windows x64.
1. Obtén el servidor. Descarga la última versión y descomprímela, por ejemplo en C:\Tools\MCPFirebird.
Si prefieres compilar desde el código fuente: Compilación y pruebas.
2. Indícale qué base de datos. Copia .env.example junto al exe como .env y completa cuatro líneas:
firebird.database=C:\data\MYAPP.FDB
firebird.user=SYSDBA
firebird.password=masterkey
firebird.client_lib=C:\Program Files\Firebird\Firebird_5_0\fbclient.dll
El zip deliberadamente no incluye fbclient.dll: la correcta es la biblioteca cliente de tu propio servidor.
3. Regístralo con tu agente de IA. Es un servidor stdio — el agente inicia el exe por sí mismo, así que toda la instalación es un solo 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 aceptan la misma forma:
{ "mcpServers": { "firebird": { "command": "C:\\Tools\\MCPFirebird\\MCPFirebird.exe" } } }
Gemini CLI y OpenCode difieren ligeramente — hay fragmentos para cada cliente en Configuración.
4. Hazle una pregunta.
Tú: ¿A qué versión de Firebird estoy conectado y qué tablas hay en la base de datos?
Tú: Esta consulta es lenta, ¿por qué?
SELECT * FROM CUSTOMERS WHERE CITY = 'Rome'Tú: Sugiere un índice que lo arregle.
Esa es toda la configuración. Si el cliente lista el servidor pero no muestra herramientas, consulta Solución de problemas, al final de esta página.
Qué puedes preguntarle
| Pregunta | Qué sucede |
|---|---|
| "Documenta la tabla CUSTOMERS" | Documentación en Markdown: columnas, clave primaria, índices, disparadores. Omite la tabla y obtienes toda la base de datos, procedimientos y paquetes incluidos |
| "¿Por qué esta consulta es lenta?" | El plan de acceso, los escaneos NATURAL y ordenamientos externos en él, el plan explicado por el motor en 3.0+, y cuánto costó realmente la consulta al ejecutarse una vez |
| "Sugiere un índice" | El remedio más barato que explica el plan — actualizar estadísticas obsoletas, reactivar un índice inactivo o crear uno — y "no hay índice, el escaneo es correcto aquí" con los números, cuando esa es la respuesta |
| "¿Qué índices puedo eliminar?" | Duplicados, prefijos redundantes, índices inactivos y de baja selectividad, con el DROP INDEX y un paso de verificación |
| "Audita esta tabla" | Clave primaria faltante, sobre-indexación, estadísticas obsoletas |
| "Sigue optimizando hasta que esta consulta deje de escanear NATURAL" | El bucle de objetivos: cambia, vuelve a medir en la base de datos y se detiene cuando la medición dice que el objetivo se cumplió — no cuando el asistente lo cree |
| "Va lenta cada tarde y nadie cambió nada" | Clasifica el síntoma antes de tocar una herramienta, luego muestrea MON$ en una ventana para mostrar qué se acumula |
| "¿Quién está conectado y qué están ejecutando?" | Cada conexión con su usuario, dirección y proceso, la sentencia que ejecuta ahora y cuánto tiempo lleva ejecutándola |
| "Haz una copia de seguridad de la base de datos" | Ejecuta gbak en segundo plano y restaura lo que escribió en una base de datos temporal, así la respuesta es "esta copia se restaura", no "existe un archivo" |
Cada análisis también cierra con lo que no descarta: un plan no puede ver contención, y una instantánea no puede ver acumulación.
→ Ejemplos trabajados, salida de herramientas textual, un recorrido completo en employee.fdb
Las herramientas
Trece herramientas, tres indicaciones, un recurso. Referencia completa — argumentos, qué decide cada una, las formas crudas de tools/call — en 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 regresa antes de que la copia de seguridad termine — consulta fb_backup_status. Necesita
firebird.backup_dir configurado en el .env, gbak.exe junto a tu fbclient.dll, y espacio en ese
disco para una segunda copia de la base de datos mientras se ejecuta la restauración de verificación.
Indicaciones: optimization_goal (itera hasta cumplir) · health_check · classify_problem.
Recurso: firebird://schema.
Nueve herramientas adicionales aparecen en tools/list y pertenecen a la edición Enterprise:
tu asistente puede verlas y decir qué haría con ellas.
Ediciones
Usarlo en tus propias bases de datos es gratis y seguirá siéndolo. Sin prueba, sin caducidad, sin clave de licencia, sin límite de asientos. Consultores: es tu herramienta, úsala en las bases de datos de tus clientes y cobra por tu tiempo. Lo único que necesita licencia es dejar que una copia salga de tus manos — redistribuirla, incrustarla en un producto que vendas u ofrecerla como servicio.
Una edición Enterprise de pago separada continúa donde termina una conexión SQL: firebird.conf, la
RAM y las CPU de la máquina, firebird.log, la API de Trace, el informe de almacenamiento físico. La quieres
cuando el esquema está en orden y la base de datos sigue lenta.
→ Ediciones, licencias y los casos trabajados · d.teti@bittime.it
Documentación
| Configuración | Requisitos previos, la referencia de .env, --env <dir>, varias bases de datos desde una compilación, fragmentos por cliente, prueba de humo manual |
| Ejemplos trabajados | Las conversaciones, salida de herramientas textual, un recorrido de optimización |
| Referencia de herramientas | Las diez herramientas, cómo decide el asesor de índices, indicaciones, recursos, herramientas Enterprise |
| Ediciones y licencias | Qué es gratis, qué necesita licencia, qué añade Enterprise |
| Compilación y pruebas | Compilación en Delphi, la matriz de pruebas 2.5→5.0, cómo usa mcp-server-delphi |
| Catálogo de problemas | Cada problema detectado, el fixture que lo provoca, el hito |
Solución de problemas
| Síntoma | Causa probable / solución |
|---|---|
| El cliente muestra el servidor pero sin herramientas | .env falta o la base de datos es inaccesible: el servidor inicia pero las herramientas fallan al conectar. Prueba con la prueba de humo manual. |
Your user name and password are not defined (SQLSTATE 28000) | Credenciales incorrectas, o un kit zip de Firebird que no incluye un SYSDBA utilizable (ver Compilación y pruebas). |
| Las herramientas de análisis devuelven vacío / sin escaneo NATURAL en una base de datos remota | Asegúrate de que firebird.host sea el host real (el analizador de planes usa el host configurado). |
fbclient.dll no encontrado / bitness incorrecto | Configura firebird.client_lib a un fbclient.dll Win64; un cliente 5.0 funciona contra 2.5-5.0. |
| stdout tiene ruido no JSON | El registro debe ir solo a archivo: mantén logger.config.file=loggerpro.stdio.json. |
| El puerto 3050 ya está en uso por otro Firebird | Usa un puerto distinto (el entorno de pruebas pone FB 2.5 en 3070 por esta razón). |
Seguridad y compatibilidad
- Solo lectura, y no por confianza. El servidor abre sus transacciones en modo solo lectura, así que un INSERT, UPDATE, DELETE o DDL es rechazado por Firebird, no por una verificación nuestra que podría equivocarse sobre lo que hace una sentencia. Importa porque tres herramientas ejecutan SQL que llega como texto del llamador —
fb_analyze_querymide el SELECT que analiza,fb_suggest_indexesmide el que asesora yfb_evaluate_goalcronometra uno. Las tres también rechazan cualquier cosa que no sea un SELECT simple antes de ejecutarla, y rechazan ejecutar una sentencia cuyos parámetros nadie vinculó; la transacción de solo lectura es lo que sostiene si un rechazo alguna vez es incorrecto. El SQL que un asesor te entrega es tuyo para ejecutarlo, cuando y si decides hacerlo. Las herramientas que aplican un cambio por sí mismas están planificadas, y cuando lleguen estarán desactivadas a menos que las actives. - Multi-versión. La detección de capacidades adapta el uso de funciones (tablas MON$, planes explicados, BOOLEAN, INT128, zonas horarias, trabajadores paralelos) al motor conectado; validado en FB 2.5 / 3.0 / 4.0 / 5.0.
- Una sola base de datos configurada por instancia del servidor (ejecuta varias instancias para varias bases de datos).
Licencia
Desde v0.2.0, licenciado bajo la
Licencia de Uso Interno PolyForm 1.0.0:
gratis en tus propias bases de datos, a cualquier escala, y se necesita una licencia solo para pasar el software a
otra persona. v0.1.0 y anteriores se publicaron bajo Apache-2.0 y siguen así para todos
los que las recibieron. Ver
Ediciones y licencias
y NOTICE.
Construido con mcp-server-delphi, que a su vez se apoya en DelphiMVCFramework. Este servidor es un ejemplo completo y real de lo que puedes construir con ellos: si estás escribiendo tu propio servidor MCP en Delphi, empieza ahí.