DB-MCP

DB MCP Gateway

Dale a Claude Code, Cursor, Windsurf o cualquier herramienta de IA compatible con MCP acceso de solo lectura a tus bases de datos — sin exponer credenciales ni arriesgar cambios de datos.

Autohospedado. Todo se ejecuta localmente. Tus contraseñas nunca salen de tu máquina.

https://github.com/user-attachments/assets/f768ff6f-3c9e-4583-9179-c7022d3b7487

Bases de datos compatibles

	Base de datos	Notas
	PostgreSQL	Todas las versiones
	MySQL	MySQL 5.7+ / MariaDB
	SQLite	Archivo local, no necesita servidor
	Amazon Redshift	SSL requerido, consultas de catálogo específicas de Redshift

---

Qué hace

En lugar de copiar y pegar resultados de consultas entre tu cliente de base de datos y tu herramienta de IA, la pasarela permite que tu IA consulte la base de datos directamente. Puede explorar esquemas, inspeccionar tablas y ejecutar consultas SELECT. No puede insertar, actualizar, eliminar ni borrar nada.

---

Inicio rápido

Opción A — Docker (recomendado, no requiere instalación local)

git clone https://github.com/mdadul/db-mcp
cd db-mcp

# Generate .env with secure random keys, then start
sh scripts/setup.sh
docker compose up

docker compose extrae la imagen precompilada de Docker Hub — no se requiere paso de compilación.
El MCP_TOKEN lo imprime setup.sh — cópialo antes de cerrar la terminal.

---

Opción B — Nativo (requiere Bun)

git clone https://github.com/mdadul/db-mcp
cd db-mcp
bun install
bun run dev   # generates .env automatically, then starts the server

Abre http://localhost:4080.
Tu MCP_TOKEN está en .env.

---

Conecta tu herramienta de IA

Claude Code (CLI)

claude mcp add --transport http db-mcp http://localhost:4080/mcp \
  --header "Authorization: Bearer <MCP_TOKEN>"

Después, reinicia Claude Code.

Cursor / Windsurf / Claude Desktop

Añade a tu mcp.json:

{
  "mcpServers": {
    "db-mcp": {
      "url": "http://localhost:4080/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_TOKEN>"
      }
    }
  }
}

Claude.ai Web

Claude.ai requiere HTTPS. Expón la pasarela a través de un túnel primero:

# Option A — Cloudflare (no account needed)
npx cloudflared tunnel --url http://localhost:4080

# Option B — ngrok
ngrok http 4080

Copia la URL de https://... desde la salida del túnel y luego añádela en Claude.ai → Configuración → Integraciones → Añadir servidor MCP.

---

Cómo usarlo con tu IA

Una vez conectado, solo pregunta de forma natural:

"¿Cuántos pedidos se crearon esta semana?" "¿Qué columnas tiene la tabla users?" "Muéstrame los últimos 10 trabajos fallidos."

La IA llamará automáticamente a las herramientas de la pasarela — sin copiar y pegar.

Herramientas disponibles

Herramienta	Qué hace
list_databases	Lista todas las bases de datos conectadas
get_database_schema	Lista las tablas (filtro de nombre opcional)
get_table_schema	Muestra columnas, índices y claves foráneas de una tabla
execute_read_query	Ejecuta una consulta SELECT (limitada a 100 filas por defecto, máximo 1000)

---

Variables de entorno

Variable	Obligatoria	Descripción
DATABASE_PATH	Sí	Ruta del almacén de metadatos SQLite local (p. ej. ./data/db-mcp.sqlite)
ENCRYPTION_KEY	Sí	Clave hexadecimal de 64 caracteres para el cifrado de credenciales. Genera: openssl rand -hex 32
MCP_TOKEN	Sí	Token Bearer para el endpoint de /mcp. Genera: openssl rand -base64 32
PORT	No	Puerto HTTP (predeterminado: 4080)

Se crea un archivo .env con valores generados al primer inicio.

---

Solución de problemas

Las herramientas no aparecen en Claude Code Reinicia Claude Code después de añadir el servidor MCP. Si siguen sin aparecer, ejecuta claude mcp list para confirmar que está registrado y que muestra ✓ Connected.

"Error al conectar" en Claude Code Comprueba que la pasarela esté en ejecución (http://localhost:4080 debería cargar) y que el token de tu configuración coincida con .env.

Errores de "Sesión no encontrada" La pasarela no tiene estado — cada solicitud es independiente. Si ves este error, vuelve a conectar el servidor MCP en tu IDE.

"La URL debe comenzar con https" (Claude.ai Web) Claude.ai bloquea HTTP sin cifrar. Usa un túnel — consulta la configuración de Claude.ai Web más arriba.

Conexión rechazada con mi base de datos Si la pasarela se ejecuta en Docker y tu base de datos está en el host, usa host.docker.internal en lugar de localhost como host.

---

Notas de seguridad

• El MCP_TOKEN controla el acceso a todas tus bases de datos a través de la pasarela. Trátalo como una contraseña.
• Las credenciales de la base de datos están cifradas con AES-256-GCM. La clave reside solo en ENCRYPTION_KEY — nunca en la base de datos.
• Solo se permiten SELECT, SHOW, DESCRIBE y EXPLAIN. Las operaciones de escritura se rechazan en la capa de la pasarela antes de llegar a la base de datos.
• Todas las consultas se registran en el panel web, en la pestaña Logs de cada base de datos.