Database Server

MCP Database Server

Un servidor de Protocolo de Contexto de Modelo (MCP) que ofrece capacidades de ejecución de consultas en múltiples bases de datos, con soporte para SQLite, PostgreSQL y MySQL. Incluye una interfaz web integrada para gestionar las conexiones de bases de datos.

Paquete NPM

Disponible en NPM: @ahmetbarut/mcp-database-server

# Use with npx (no installation required)
npx @ahmetbarut/mcp-database-server

# Or install globally
npm install -g @ahmetbarut/mcp-database-server

Características

• Soporte multi-base de datos: SQLite, PostgreSQL y MySQL con conexiones reales
• Interfaz web: Interfaz de navegador integrada para gestionar conexiones de bases de datos
• Almacén de configuración SQLite: Todas las configuraciones de conexión se guardan localmente en ~/.mcp-database-server/connections.db
• Cumplimiento del protocolo MCP: Implementación JSON-RPC completa con soporte total de herramientas
• Detección automática inteligente: Selecciona automáticamente la única conexión activa para consultas
• Recuperación de conexión: Reintenta conexiones fallidas con informes de error detallados
• Seguridad primero: Consultas parametrizadas, protección contra inyección SQL, registro de auditoría
• Soporte SSL: SSL configurable por conexión
• Seguridad de tipos: Implementación completa en TypeScript con validación Zod
• Compatibilidad con Node.js v23: Funciona con las versiones más recientes de Node.js

Inicio rápido

npx @ahmetbarut/mcp-database-server

El servidor se inicia y la interfaz web se abre en http://localhost:3693. Añade tus conexiones de bases de datos desde el navegador.

Interfaz web

La interfaz web integrada proporciona una interfaz visual para gestionar conexiones de bases de datos:

• Añadir/Editar/Eliminar conexiones de bases de datos (SQLite, PostgreSQL, MySQL)
• Probar conexiones antes de guardarlas
• Interruptor SSL para bases de datos de red
• Almacenamiento persistente: las conexiones sobreviven a los reinicios del servidor

Accede a ella en http://localhost:3693 cuando el servidor esté en ejecución.

Variables de entorno

Variable	Valor predeterminado	Descripción
WEB_UI_PORT	3693	Puerto de la interfaz web
WEB_UI_ENABLED	true	Activar/desactivar la interfaz web
LOG_LEVEL	info	Nivel de registro (debug, info, warn, error)

Configuración del cliente MCP

Claude Desktop

Añade a tu claude_desktop_config.json:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@ahmetbarut/mcp-database-server"]
    }
  }
}

Cursor IDE

Añade a ~/.cursor/mcp.json:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@ahmetbarut/mcp-database-server"]
    }
  }
}

Puerto personalizado

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@ahmetbarut/mcp-database-server"],
      "env": {
        "WEB_UI_PORT": "4000"
      }
    }
  }
}

Después de iniciar, abre la interfaz web en tu navegador para añadir conexiones de bases de datos.

Herramientas MCP

execute_query

Ejecuta consultas SQL en una conexión de base de datos con soporte de consultas parametrizadas.

{
  "connection_name": "my-postgres",
  "query": "SELECT * FROM users WHERE status = $1",
  "parameters": ["active"]
}

list_databases

Lista las bases de datos de una conexión específica o de todas las conexiones configuradas. Soporta detección automática inteligente cuando solo hay una conexión activa.

{
  "connection_name": "my-postgres"
}

list_connections

Lista todas las conexiones de bases de datos con estado y detalles.

{
  "include_credentials": false
}

retry_failed_connections

Reintenta conexiones de bases de datos que hayan fallado.

{
  "connection_name": "my-postgres"
}

Configuración de conexión

Todas las conexiones de bases de datos se gestionan a través de la interfaz web y se almacenan en una base de datos SQLite local en ~/.mcp-database-server/connections.db.

Tipos de bases de datos compatibles

SQLite

• Ruta al archivo de base de datos

PostgreSQL

• Host, puerto, base de datos, nombre de usuario, contraseña
• Soporte SSL (opcional)

MySQL

• Host, puerto, base de datos, nombre de usuario, contraseña
• Soporte SSL (opcional)

Ajustes de conexión

Ajuste	Valor predeterminado	Descripción
maxConnections	10	Tamaño máximo del grupo de conexiones
timeout	30000	Tiempo de espera de conexión en milisegundos
ssl	false	Activar SSL para la conexión

Desarrollo

# Clone the repository
git clone https://github.com/ahmetbarut/mcp-database-server.git
cd mcp-database-server

# Install dependencies
npm install

# Development mode (hot-reload)
npm run dev

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint
npm run lint

# Type check
npm run type-check

Estructura del proyecto

mcp-database-server/
├── src/
│   ├── index.ts              # CLI entry point
│   ├── server/
│   │   └── mcp-server.ts     # MCP server, tool handlers
│   ├── database/
│   │   ├── base.ts           # Abstract base driver
│   │   ├── factory.ts        # Driver factory & connection manager
│   │   └── drivers/          # SQLite, PostgreSQL, MySQL drivers
│   ├── config/
│   │   ├── settings.ts       # Config manager (loads from SQLite store)
│   │   └── config-store.ts   # SQLite-backed connection storage
│   ├── web/
│   │   ├── web-server.ts     # HTTP server for Web UI
│   │   ├── routes.ts         # REST API endpoints
│   │   └── ui.ts             # Embedded HTML/CSS/JS interface
│   ├── types/                # TypeScript types & Zod schemas
│   └── utils/                # Logger, exceptions, helpers
├── tests/unit/               # Jest test suites
└── dist/                     # Compiled output

Arquitectura

npx @ahmetbarut/mcp-database-server
    │
    ├── MCPDatabaseServer
    │   ├── MCP stdio transport (JSON-RPC)
    │   ├── DatabaseConnectionManager
    │   └── WebUIServer (http://localhost:3693)
    │
    └── ConnectionConfigStore (~/.mcp-database-server/connections.db)
        └── SQLite database with connection configs

1. Almacén de configuración carga las conexiones guardadas desde la base de datos SQLite local
2. Gestor de conexiones inicializa los controladores de base de datos para cada configuración
3. Servidor MCP expone herramientas mediante JSON-RPC sobre stdio
4. Interfaz web proporciona operaciones CRUD basadas en navegador para conexiones mediante API REST

Seguridad

• Consultas parametrizadas: evita la inyección SQL
• Enmascaramiento de credenciales: las contraseñas se ocultan en la salida de list_connections
• Registro de auditoría: todas las operaciones se registran mediante Winston
• Validación de entrada: esquemas Zod para toda la configuración

Pruebas

Test Suites: 2 passed, 2 total
Tests:       23 passed, 23 total

npm test               # Run all tests
npm run test:watch     # Watch mode
npm run test:coverage  # Coverage report

Solución de problemas

La interfaz web no es accesible

• Comprueba si el puerto 3693 ya está en uso
• Prueba con un puerto diferente: WEB_UI_PORT=4000

La conexión falló

• Usa el botón "Probar conexión" en la interfaz web antes de guardar
• Verifica que el servidor de base de datos esté en ejecución y sea accesible
• Comprueba las credenciales y la conectividad de red
• Para PostgreSQL: desactiva SSL si el servidor no lo soporta

El cliente MCP no puede conectarse

• Asegúrate de que npx @ahmetbarut/mcp-database-server se ejecute sin errores
• Reinicia el cliente MCP después de los cambios de configuración
• Revisa los registros del cliente MCP para obtener detalles del error

Licencia

Licencia MIT: consulta el archivo LICENSE para más detalles.

Contribuciones

1. Sigue los estándares de codificación de TypeScript
2. Añade pruebas para las nuevas funcionalidades
3. Actualiza la documentación para los cambios de API
4. Sigue las directrices de seguridad

Soporte

Para incidencias y preguntas, usa el rastreador de incidencias de GitHub.