MCP Firebird

Un servidor MCP para bases de datos Firebird SQL, que permite a los LLMs acceder, analizar y manipular contenido de bases de datos de forma segura.

GitHub

Prueba este MCPPatrocinado

Documentación

MCP Firebird

Implementación del MCP (Model Context Protocol) de Anthropic para bases de datos Firebird.

Ejemplo de Uso

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

¿Qué es MCP Firebird?

MCP Firebird es un servidor que implementa el Model Context Protocol (MCP) de Anthropic para bases de datos SQL Firebird. Permite que los Modelos de Lenguaje de Gran Escala (LLMs) como Claude accedan, analicen y manipulen datos en bases de datos Firebird de forma segura y controlada.

🚀 Novedades en MCP 2.7+ (Rendimiento y Seguridad)

Este servidor ha sido actualizado para soportar los estándares empresariales más recientes en el ecosistema MCP:

⚡ Agrupación de Conexiones (Cero Latencia): Las consultas repetitivas a la base de datos ahora utilizan conexiones persistentes en memoria, omitiendo por completo la sobrecarga del protocolo de enlace y ejecutándose casi instantáneamente.
🎯 Eventos Proactivos (Disparadores): Integración nativa con POST_EVENT de Firebird. El servidor escucha eventos de la base de datos en tiempo real y notifica proactivamente al cliente de IA (por ejemplo, Claude/n8n) sin requerir sondeos continuos.
- Ejemplo Rápido: Pide a tu agente que subscribe_to_event con NEW_ORDER. Cuando Firebird ejecute POST_EVENT 'NEW_ORDER', ¡tu agente recibirá una notificación al instante! Lee la guía detallada y los ejemplos.
🛡️ Autorización Gestionada Empresarial (EMA): ¿No quieres exponer tu contraseña real de la base de datos (SYSDBA) al cliente LLM? Habilita EMA para requerir un --api-key en las conexiones entrantes. El servidor intercepta este token e inyecta la contraseña real de forma segura bajo el capó.
- Ejemplo Rápido: Inicia el servidor con --password "real_password" --api-key "my-secure-token". El cliente remoto se conecta usando Authorization: Bearer my-secure-token. ¡La contraseña de la base de datos nunca sale del servidor! Lee la guía detallada en Seguridad.
🌊 Transmisión Bidireccional (HTTP Transmisible / SSE): Perfecto para n8n o implementaciones remotas. Proporciona transmisión de eventos en tiempo real y sesiones con estado a través de HTTP.
- Ejemplo Rápido: Inicia el servidor con TRANSPORT_TYPE=sse SSE_PORT=3003. Configura tu cliente (como n8n) para conectarse a http://YOUR_SERVER:3003/mcp. Lee la guía detallada.

🏗️ Modos de Transporte y Arquitectura

MCP Firebird soporta múltiples arquitecturas de implementación. Recomendamos encarecidamente usar HTTP Transmisible (SSE) para implementaciones modernas, empresariales o remotas.

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

Ideal para conectar n8n, plataformas en la nube, agentes remotos o herramientas que no residen en la misma máquina que tu base de datos.

Instalación:

npm install -g mcp-firebird

Ejecutar el Servidor: Configura tus variables de entorno (o el archivo .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

Conexión del Cliente: Tu cliente de IA (por ejemplo, MCP Inspector, n8n) se conecta a http://localhost:3003 y, gracias a EMA, solo necesita proporcionar la CLAVE API en lugar de la contraseña real de la base de datos.

2. [LOCAL / LEGADO] Transporte Estándar (STDIO)

Este es el método clásico recomendado solo para uso personal en la misma máquina (por ejemplo, Claude Desktop). Claude inicia su propio subproceso de MCP Firebird en segundo plano.

Características Principales

Consultas SQL: Ejecuta consultas SQL en bases de datos Firebird
Análisis de Esquema: Obtén información detallada sobre tablas, columnas y relaciones
Metadatos de Base de Datos: Inspecciona disparadores, procedimientos almacenados, funciones y paquetes con código fuente
Análisis de Rendimiento: Analiza el rendimiento de las consultas y sugiere optimizaciones
Seguridad: Incluye validación de consultas SQL, EMA y Agrupación de Conexiones.
Soporte de Doble Controlador: Elige entre instalación simple (predeterminada) o controlador nativo con soporte de cifrado de cable.

🔒 Soporte de Cifrado de Cable

MCP Firebird soporta dos opciones de controlador:

Controlador	Instalación	Cifrado de Cable	Caso de Uso
JavaScript Puro (predeterminado)	✅ Simple (`npx`)	❌ No	La mayoría de los usuarios, configuración rápida
Controlador Nativo (opcional)	⚠️ Complejo (requiere herramientas de compilación)	✅ Sí	Empresarial, se requiere seguridad

Inicio Rápido (Predeterminado - Sin Cifrado de Cable)

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

Avanzado (Con Soporte de Cifrado de Cable)

⚠️ CRÍTICO: npx NO funciona con el controlador nativo. DEBES instalar globalmente.

⚠️ IMPORTANTE: El cifrado de cable debe configurarse en el servidor Firebird (firebird.conf), no en el cliente.

Configuración del Servidor (requerida primero):

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

Instalación del Cliente (DEBE 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 qué no npx? Cuando npx ejecuta un paquete desde su caché temporal, no puede acceder a módulos instalados globalmente como node-firebird-driver-native. Ambos paquetes deben instalarse globalmente en la misma ubicación.

📚 Para instrucciones de instalación detalladas, consulta:

Guía de Instalación del Controlador Nativo - Paso a paso para Windows/Linux/macOS
Guía de Cifrado de Cable
Guía de Instalación Avanzada

Instalación Manual

Versión Estable

# Global installation
npm install -g mcp-firebird

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

Características Estables (v2.2.3):

🐛 CORREGIDO: Error de análisis JSON SSE - resuelve errores "Invalid message: [object Object]"
✨ Soporte de transporte HTTP Transmisible (MCP 2025-03-26)
🔄 Servidor unificado con detección automática de protocolo
📊 Gestión y monitoreo de sesiones mejorados
🛠️ Integración moderna del SDK MCP (v1.13.2)
🔧 Manejo de errores y registro mejorados
🧪 Suite de pruebas integral con 9+ pruebas para funcionalidad SSE

Versión Alfa (Características Más Recientes)

# 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

Características Alfa (v2.4.0-alpha.0):

NUEVO: Listo para el próximo ciclo de desarrollo
✨ Todas las características estables de v2.2.3 incluidas
🔄 Servidor unificado con detección automática de protocolo
📊 Gestión y monitoreo de sesiones mejorados
🛠️ Integración moderna del SDK MCP (v1.13.2)
🔧 Manejo de errores y registro mejorados
🧪 Suite de pruebas integral con 9+ pruebas para funcionalidad SSE
📚 Documentación mejorada con guías de solución de problemas

Nota: La corrección del error de análisis JSON SSE ahora está disponible en la versión estable v2.2.3

Para la integración con VSCode y GitHub Copilot, consulta Integración con VSCode.

Uso Básico

Con Claude Desktop

Edita la configuración de Claude Desktop:

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

Agrega la configuración de 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"
    }
  }
}

Reinicia Claude Desktop

Configuración del Transporte

MCP Firebird soporta múltiples protocolos de transporte para adaptarse a diferentes necesidades de clientes y escenarios de implementación.

Transporte STDIO (Predeterminado)

El transporte STDIO es el método estándar para la integración con Claude Desktop:

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

Transporte SSE (Eventos Enviados por el Servidor)

El transporte SSE permite que el servidor se ejecute como un servicio web, útil para aplicaciones web y acceso remoto:

Configuración Básica de 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

Variables de Entorno 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

Conexión del Cliente SSE

Una vez que el servidor SSE está en ejecución, los clientes pueden conectarse a:

Punto de Conexión SSE: http://localhost:3003/sse
Punto de Conexión de Mensajes: http://localhost:3003/messages
Verificación de Salud: http://localhost:3003/health

Transporte HTTP Transmisible (Moderno)

El protocolo MCP más reciente que soporta comunicación bidireccional:

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

Transporte Unificado (Recomendado)

Soporta simultáneamente los protocolos SSE y HTTP Transmisible con detección 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

Puntos de Conexión del Servidor Unificado

SSE (Legado): http://localhost:3003/sse
HTTP Transmisible (Moderno): http://localhost:3003/mcp
Auto-Detección: http://localhost:3003/mcp-auto
Verificación de Salud: http://localhost:3003/health

Ejemplos de Configuración

Configuración de Desarrollo (SSE)

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

Configuración de Producción (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 con 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

Configuración Avanzada de SSE

Gestión de Sesiones

Configura tiempos de espera y límites de sesión:

# 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

Configuración CORS

Para aplicaciones de navegador, restringe el acceso a uno o más orígenes separados por comas. El valor predeterminado es * con credenciales de navegador deshabilitadas, por lo que los clientes MCP STDIO y Bearer-token existentes permanecen compatibles:

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

npx mcp-firebird --transport-type sse

La versión estable 2.11.0 incluye todas las mejoras de seguridad y compatibilidad de 2.11.0-alpha.1 a alpha.4, incluida la configuración JSON en línea y la corrección de análisis EXTRACT/SUBSTRING/TRIM. Instala con npm install -g mcp-firebird@latest, o fija mcp-firebird@2.11.0. Las políticas existentes que contienen configuraciones previamente inactivas ahora las aplican; revisa la guía de migración.

Las escrituras SQL sin procesar están deshabilitadas por defecto. 2.11.0 preserva el interruptor histórico ALLOW_RAW_SQL=true para escrituras, incluido DDL, sin requerir nuevas banderas. Las restricciones explícitamente configuradas de operación/tabla/fila/enmascaramiento/rol y sql.allowDDL=false nunca se omiten con ese interruptor. Consulta la guía de seguridad para controles de participación voluntaria y el formato estructurado de filtro get-table-data.

Los archivos de seguridad personalizados se pueden cargar con --security-config /absolute/path/security-config.json o la variable de entorno FIREBIRD_SECURITY_CONFIG. SECURITY_CONFIG y SECURITY_CONFIG_PATH son alias de respaldo, en ese orden; la opción de CLI tiene prioridad sobre las variables de entorno. Usa un objeto JSON como {"security":{"allowedTables":["EMPLOYEES"],"allowedOperations":["SELECT"],"maxRows":100}}. También se admiten archivos CommonJS de confianza. Reinicia después de cambiar la política y verifica Loaded security configuration from .... A partir de 2.11.0-alpha.2, los archivos seleccionados inválidos o faltantes detienen la inicialización en lugar de aplicar silenciosamente los valores predeterminados. Consulta la guía de seguridad.

A partir de 2.11.0-alpha.1, establece FIREBIRD_SECURITY_JSON a esa misma cadena JSON para configurar la seguridad sin un archivo. También se admiten opciones SQL. En 2.11.0-alpha.3, las restricciones avanzadas son de participación voluntaria: sin cuotas de recursos implícitas, plazos, denegación de catálogo o nuevas restricciones de rutina. Establece solo los controles que necesites; por ejemplo, {"security":{"maxRows":100}} activa solo ese límite de filas. Las políticas explícitas se aplican, incluidas las opciones que las versiones anteriores no aplicaban. Las rutas de archivo tienen prioridad. Solo un administrador/lanzador de confianza puede establecer la variable; los clientes HTTP/SSE no pueden cambiarla. El JSON en línea está limitado a 64 KiB (UTF-8), validado sin ejecutar código y no registrado por el cargador. Las políticas inválidas rechazan la inicialización. Desactiva la variable para deshabilitar esa fuente y reinicia después de los cambios. Revisa el aviso de migración, los ejemplos de configuración y la revisión de implementación.

Soporte SSL/TLS

Para implementaciones de producción, usa un proxy inverso 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;
    }
}

Solución de Problemas

Problemas de Conexión con Firebird

Incompatibilidad de Cifrado de Cable (Firebird 3.0+) ⚠️ CRÍTICO

Error: Incompatible wire encryption levels requested on client and server

IMPORTANTE: La biblioteca node-firebird NO admite el cifrado de cable de Firebird 3.0+. El parámetro --wire-crypt NO funciona.

ÚNICA Solución: DEBES deshabilitar el cifrado de cable en el servidor Firebird:

Para Firebird 3.0, agrega a firebird.conf:
```
WireCrypt = Disabled
AuthServer = Srp, Legacy_Auth
```
Para Firebird 4.0+, agrega 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
```
Si no puedes cambiar la configuración del servidor, consulta Limitación del Cifrado de Cable para alternativas.
Problemas de Ruta de Base de Datos en Linux/Unix

Problema: Cadenas de conexión remotas o rutas Unix que no funcionan

Solución: Esto está corregido en v2.4.0-alpha.1+. Las siguientes rutas ahora funcionan correctamente:
- Remota: server:/path/to/database.fdb
- Unix absoluta: /var/lib/firebird/database.fdb
- Basada en IP: 192.168.1.100:/data/db.fdb
Error de E/S con Rutas de Mayúsculas y Minúsculas Mixtas en Windows

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

Problema: La ruta de la base de datos con mayúsculas y minúsculas mixtas (por ejemplo, C:\MyData\database.fdb) causa errores

Soluciones Alternativas:
- Usa rutas completamente en mayúsculas: C:\MYDATA\DATABASE.FDB
- Usa barras diagonales: C:/MyData/database.fdb
- Consulta la Documentación de Corrección del Cifrado de Cable para más detalles

Problemas de Conexión SSE

Conexión Rechazada

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

# Check port availability
netstat -an | grep 3003

Tiempo de Sesión Agotado

# Increase session timeout
export SSE_SESSION_TIMEOUT_MS=3600000  # 1 hour

Errores CORS

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

Problemas de Memoria

# Reduce max sessions
export MAX_SESSIONS=100

# Enable more frequent cleanup
export SESSION_CLEANUP_INTERVAL_MS=30000

Problemas de Análisis JSON (Corregido en 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: Las versiones anteriores a 2.3.0-alpha.1 tenían un error donde las solicitudes POST al endpoint /messages fallaban al analizar correctamente el cuerpo JSON. Esto se ha corregido con un manejo mejorado de middleware para ambos tipos de contenido application/json y text/plain.

Monitoreo y Registro

# 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'

Documentación

Para obtener información más detallada, consulte los siguientes documentos:

Primeros Pasos

Instalación Completa
Opciones de Configuración
Herramientas Disponibles
Herramientas de Metadatos de Base de Datos - Inspeccione disparadores, procedimientos, funciones y paquetes
Referencia de Recursos, Herramientas y Prompts - Guía completa de todas las capacidades de MCP

Protocolos de Transporte

Configuración de Transporte

Guías de Integración

Temas Avanzados

Seguridad
Solución de Problemas
Corrección de Cifrado de Cable - Compatibilidad con Firebird 3.0+ y corrección de ruta en Linux

Ejemplos y Casos de Uso

Casos de Uso y Ejemplos

Apoye el Proyecto

Donaciones

Si encuentra útil MCP Firebird para su trabajo o proyectos, considere apoyar su desarrollo mediante una donación. Sus contribuciones ayudan a mantener y mejorar esta herramienta.

GitHub Sponsors: Patrocine a @PuroDelphi
PayPal: Done a través de PayPal

Contrate Nuestros Agentes de IA

Otra excelente manera de apoyar este proyecto es contratando nuestros agentes de IA a través de Asistentes Autónomos. Ofrecemos asistentes de IA especializados para diversas necesidades empresariales, ayudándole a automatizar tareas y mejorar la productividad.

Soporte Prioritario

⭐ Los donantes, patrocinadores y clientes reciben soporte prioritario y asistencia con problemas, solicitudes de funciones y orientación de implementación. Si bien nos esforzamos por ayudar a todos los usuarios, aquellos que apoyan financieramente el proyecto recibirán tiempos de respuesta más rápidos y asistencia dedicada.

Su apoyo es muy apreciado y ayuda a garantizar el desarrollo continuo de MCP Firebird.

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENCIA para más detalles.