Multi Database MCP Server

Descripción General

El Servidor MCP de Bases de Datos proporciona una forma estandarizada para que los modelos de IA interactúen con múltiples bases de datos simultáneamente. Construido sobre el framework FreePeak/cortex, permite a los asistentes de IA ejecutar consultas SQL, gestionar transacciones, explorar esquemas y analizar el rendimiento en diferentes sistemas de bases de datos a través de una interfaz unificada.

Conceptos Clave

Soporte Multi-Base de Datos

A diferencia de los conectores de bases de datos tradicionales, el Servidor MCP de Bases de Datos puede conectarse e interactuar con múltiples bases de datos de forma concurrente:

{
  "connections": [
    {
      "id": "mysql1",
      "type": "mysql",
      "host": "localhost",
      "port": 3306,
      "name": "db1",
      "user": "user1",
      "password": "password1"
    },
    {
      "id": "postgres1",
      "type": "postgres",
      "host": "localhost",
      "port": 5432,
      "name": "db2",
      "user": "user2",
      "password": "password2"
    },
    {
      "id": "oracle1",
      "type": "oracle",
      "host": "localhost",
      "port": 1521,
      "service_name": "XEPDB1",
      "user": "user3",
      "password": "password3"
    }
  ]
}

Generación Dinámica de Herramientas

Para cada base de datos conectada, el servidor genera automáticamente herramientas especializadas:

// For a database with ID "mysql1", these tools are generated:
query_mysql1       // Execute SQL queries
execute_mysql1     // Run data modification statements
transaction_mysql1 // Manage transactions
schema_mysql1      // Explore database schema
performance_mysql1 // Analyze query performance

Arquitectura Limpia

El servidor sigue los principios de Arquitectura Limpia con estas capas:

1. Capa de Dominio: Entidades de negocio e interfaces principales
2. Capa de Repositorio: Implementaciones de acceso a datos
3. Capa de Casos de Uso: Lógica de negocio de la aplicación
4. Capa de Entrega: Interfaces externas (herramientas MCP)

Características

• Soporte Multi-Base de Datos Simultáneo: Conéctese a múltiples bases de datos MySQL, PostgreSQL, SQLite y Oracle de forma concurrente
• Modo de Carga Perezosa: Difiera el establecimiento de conexiones hasta el primer uso - perfecto para configuraciones con 10+ bases de datos (habilítelo con la bandera --lazy-loading)
• Generación de Herramientas Específicas por Base de Datos: Crea automáticamente herramientas especializadas para cada base de datos conectada
• Arquitectura Limpia: Diseño modular con separación clara de responsabilidades
• Compatibilidad con OpenAI Agents SDK: Compatibilidad total para una integración fluida con asistentes de IA
• Herramientas Dinámicas de Base de Datos: Ejecute consultas, ejecute sentencias, gestione transacciones, explore esquemas, analice el rendimiento
• Interfaz Unificada: Patrones de interacción consistentes entre diferentes tipos de bases de datos
• Gestión de Conexiones: Configuración simple para múltiples conexiones de bases de datos
• Verificación de Salud: Validación automática de la conectividad de la base de datos al inicio

Bases de Datos Soportadas

Base de Datos	Estado	Características
MySQL	✅ Soporte Completo	Consultas, Transacciones, Análisis de Esquemas, Información de Rendimiento
PostgreSQL	✅ Soporte Completo (v9.6-17)	Consultas, Transacciones, Análisis de Esquemas, Información de Rendimiento
SQLite	✅ Soporte Completo	Bases de datos basadas en archivos y en memoria, soporte de cifrado SQLCipher
Oracle	✅ Soporte Completo (10g-23c)	Consultas, Transacciones, Análisis de Esquemas, RAC, Cloud Wallet, TNS
TimescaleDB	✅ Soporte Completo	Hipertablas, Consultas de Series Temporales, Agregados Continuos, Compresión, Políticas de Retención

Opciones de Despliegue

El Servidor MCP de Bases de Datos se puede desplegar de múltiples maneras para adaptarse a diferentes entornos y necesidades de integración:

Despliegue con Docker

# Pull the latest image
docker pull freepeak/db-mcp-server:latest

# Run with mounted config file
docker run -p 9092:9092 \
  -v $(pwd)/config.json:/app/my-config.json \
  -e TRANSPORT_MODE=sse \
  -e CONFIG_PATH=/app/my-config.json \
  -e DB_MCP_API_KEY=replace-me-with-a-long-random-string \
  freepeak/db-mcp-server

Nota: Monte en /app/my-config.json ya que el contenedor tiene un archivo predeterminado en /app/config.json.

Autenticación con Clave API

Los transportes SSE y streamable-HTTP aceptan un encabezado Authorization: Bearer <key>. Establezca DB_MCP_API_KEY (o pase -api-key) al lanzar el contenedor Docker; los clientes deben entonces enviar el token de portador correspondiente en cada solicitud:

curl -H "Authorization: Bearer replace-me-with-a-long-random-string" \
     http://localhost:9092/sse

Cuando no se configura una clave API, el transporte permanece abierto (uso de un solo usuario / desarrollo). El middleware reside en internal/delivery/mcp.APIKeyAuth y se exporta para que pueda componerlo con su propio proxy inverso si coloca el contenedor detrás de nginx, Caddy o Traefik.

Modo STDIO (Integración con IDE)

# Run the server in STDIO mode
./bin/server -t stdio -c config.json

Para la integración con Cursor IDE, agregue a .cursor/mcp.json:

{
  "mcpServers": {
    "stdio-db-mcp-server": {
      "command": "/path/to/db-mcp-server/server",
      "args": ["-t", "stdio", "-c", "/path/to/config.json"]
    }
  }
}

Modo SSE (Eventos Enviados por el Servidor)

# Default configuration (localhost:9092)
./bin/server -t sse -c config.json

# Custom host and port
./bin/server -t sse -host 0.0.0.0 -port 8080 -c config.json

Punto de conexión del cliente: http://localhost:9092/sse

Instalación desde Código Fuente

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

# Build the server
make build

# Run the server
./bin/server -t sse -c config.json

Configuración

Archivo de Configuración de Bases de Datos

Cree un archivo config.json con sus conexiones de bases de datos:

{
  "connections": [
    {
      "id": "mysql1",
      "type": "mysql",
      "host": "mysql1",
      "port": 3306,
      "name": "db1",
      "user": "user1",
      "password": "password1",
      "query_timeout": 60,
      "max_open_conns": 20,
      "max_idle_conns": 5,
      "conn_max_lifetime_seconds": 300,
      "conn_max_idle_time_seconds": 60
    },
    {
      "id": "postgres1",
      "type": "postgres",
      "host": "postgres1",
      "port": 5432,
      "name": "db1",
      "user": "user1",
      "password": "password1"
    },
    {
      "id": "sqlite_app",
      "type": "sqlite",
      "database_path": "./data/app.db",
      "journal_mode": "WAL",
      "cache_size": 2000,
      "read_only": false,
      "use_modernc_driver": true,
      "query_timeout": 30,
      "max_open_conns": 1,
      "max_idle_conns": 1
    },
    {
      "id": "sqlite_encrypted",
      "type": "sqlite",
      "database_path": "./data/secure.db",
      "encryption_key": "your-secret-key-here",
      "journal_mode": "WAL",
      "use_modernc_driver": false
    },
    {
      "id": "sqlite_memory",
      "type": "sqlite",
      "database_path": ":memory:",
      "cache_size": 1000,
      "use_modernc_driver": true
    }
  ]
}

Opciones de Línea de Comandos

# Basic syntax
./bin/server -t <transport> -c <config-file>

# SSE transport options
./bin/server -t sse -host <hostname> -port <port> -c <config-file>

# Lazy loading mode (recommended for 10+ databases)
./bin/server -t stdio -c <config-file> --lazy-loading

# Customize log directory (useful for multi-project setups)
./bin/server -t stdio -c <config-file> -log-dir /tmp/db-mcp-logs

# Inline database configuration
./bin/server -t stdio -db-config '{"connections":[...]}'

# Environment variable configuration
export DB_CONFIG='{"connections":[...]}'
./bin/server -t stdio

Banderas Disponibles:

• -t, -transport: Modo de transporte (stdio o sse)
• -c, -config: Ruta al archivo de configuración de bases de datos
• -p, -port: Puerto del servidor para modo SSE (predeterminado: 9092)
• -h, -host: Host del servidor para modo SSE (predeterminado: localhost)
• -log-level: Nivel de registro (debug, info, warn, error)
• -log-dir: Directorio para archivos de registro (predeterminado: ./logs en el directorio actual)
• -db-config: Configuración de bases de datos JSON en línea

Opciones de Configuración de SQLite

Al usar bases de datos SQLite, puede aprovechar estas opciones de configuración adicionales:

Parámetros de Conexión SQLite

Parámetro	Tipo	Predeterminado	Descripción
database_path	string	Requerido	Ruta al archivo de base de datos SQLite o :memory: para en memoria
encryption_key	string	-	Clave para bases de datos cifradas con SQLCipher
read_only	boolean	false	Abrir la base de datos en modo solo lectura
cache_size	integer	2000	Tamaño de caché de SQLite en páginas
journal_mode	string	"WAL"	Modo de diario: DELETE, TRUNCATE, PERSIST, WAL, OFF
use_modernc_driver	boolean	true	Usar modernc.org/sqlite (sin CGO) o mattn/go-sqlite3

Ejemplos de SQLite

Base de Datos Básica de Archivo

{
  "id": "my_sqlite_db",
  "type": "sqlite",
  "database_path": "./data/myapp.db",
  "journal_mode": "WAL",
  "cache_size": 2000
}

Base de Datos Cifrada (SQLCipher)

{
  "id": "encrypted_db",
  "type": "sqlite",
  "database_path": "./data/secure.db",
  "encryption_key": "your-secret-encryption-key",
  "use_modernc_driver": false
}

Base de Datos en Memoria

{
  "id": "memory_db",
  "type": "sqlite",
  "database_path": ":memory:",
  "cache_size": 1000
}

Base de Datos de Solo Lectura

{
  "id": "reference_data",
  "type": "sqlite",
  "database_path": "./data/reference.db",
  "read_only": true,
  "journal_mode": "DELETE"
}

Opciones de Configuración de Oracle

Al usar bases de datos Oracle, puede aprovechar estas opciones de configuración adicionales:

Parámetros de Conexión Oracle

Parámetro	Tipo	Predeterminado	Descripción
host	string	Requerido	Host de la base de datos Oracle
port	integer	1521	Puerto del listener de Oracle
service_name	string	-	Nombre del servicio (recomendado para RAC)
sid	string	-	Identificador del sistema (heredado, use service_name en su lugar)
user	string	Requerido	Nombre de usuario de la base de datos
password	string	Requerido	Contraseña de la base de datos
wallet_location	string	-	Ruta al directorio del wallet de Oracle Cloud
tns_admin	string	-	Ruta al directorio que contiene tnsnames.ora
tns_entry	string	-	Entrada nombrada de tnsnames.ora
edition	string	-	Nombre de edición de Redefinición Basada en Ediciones
pooling	boolean	false	Habilitar agrupación de conexiones a nivel de controlador
standby_sessions	boolean	false	Permitir consultas en bases de datos en espera
nls_lang	string	AMERICAN_AMERICA.AL32UTF8	Configuración del conjunto de caracteres

Ejemplos de Oracle

Conexión Básica de Oracle (Desarrollo)

{
  "id": "oracle_dev",
  "type": "oracle",
  "host": "localhost",
  "port": 1521,
  "service_name": "XEPDB1",
  "user": "testuser",
  "password": "testpass",
  "max_open_conns": 50,
  "max_idle_conns": 10,
  "conn_max_lifetime_seconds": 1800
}

Oracle con SID (Heredado)

{
  "id": "oracle_legacy",
  "type": "oracle",
  "host": "oracledb.company.com",
  "port": 1521,
  "sid": "ORCL",
  "user": "app_user",
  "password": "app_password"
}

Oracle Cloud Autonomous Database (con Wallet)

{
  "id": "oracle_cloud",
  "type": "oracle",
  "user": "ADMIN",
  "password": "your-cloud-password",
  "wallet_location": "/path/to/wallet_DBNAME",
  "service_name": "dbname_high"
}

Oracle RAC (Real Application Clusters)

{
  "id": "oracle_rac",
  "type": "oracle",
  "host": "scan.company.com",
  "port": 1521,
  "service_name": "production",
  "user": "app_user",
  "password": "app_password",
  "max_open_conns": 100,
  "max_idle_conns": 20
}

Oracle con Entrada TNS

{
  "id": "oracle_tns",
  "type": "oracle",
  "tns_admin": "/opt/oracle/network/admin",
  "tns_entry": "PROD_DB",
  "user": "app_user",
  "password": "app_password"
}

Oracle con Redefinición Basada en Ediciones

{
  "id": "oracle_ebr",
  "type": "oracle",
  "host": "oracledb.company.com",
  "port": 1521,
  "service_name": "production",
  "user": "app_user",
  "password": "app_password",
  "edition": "v2_0"
}

Prioridad de la Cadena de Conexión Oracle

Cuando se configuran múltiples métodos de conexión, se utiliza la siguiente prioridad:

1. Entrada TNS (si tns_entry y tns_admin están configurados)
2. Wallet (si wallet_location está configurado) - para Oracle Cloud
3. Estándar (host:puerto/nombre_servicio) - método predeterminado

Herramientas Disponibles

Para cada base de datos conectada, el Servidor MCP de Bases de Datos genera automáticamente estas herramientas especializadas:

Herramientas de Consulta

Nombre de la Herramienta	Descripción
query_<db_id>	Ejecute consultas SELECT y obtenga resultados como un conjunto de datos tabular
execute_<db_id>	Ejecute sentencias de manipulación de datos (INSERT, UPDATE, DELETE)
transaction_<db_id>	Inicie, confirme y revierta transacciones

Herramientas de Esquema

Nombre de la Herramienta	Descripción
schema_<db_id>	Obtenga información sobre tablas, columnas, índices y claves foráneas
generate_schema_<db_id>	Genere SQL o código a partir del esquema de la base de datos

Herramientas de Rendimiento

Nombre de la Herramienta	Descripción
performance_<db_id>	Analice el rendimiento de las consultas y obtenga sugerencias de optimización

Herramientas de TimescaleDB

Para bases de datos PostgreSQL con la extensión TimescaleDB, estas herramientas especializadas adicionales están disponibles:

Nombre de la Herramienta	Descripción
timescaledb_<db_id>	Realice operaciones generales de TimescaleDB
create_hypertable_<db_id>	Convierta una tabla estándar en una hipertabla de TimescaleDB
list_hypertables_<db_id>	Liste todas las hipertablas en la base de datos
time_series_query_<db_id>	Ejecute consultas optimizadas de series temporales con agrupación
time_series_analyze_<db_id>	Analice patrones de datos de series temporales
continuous_aggregate_<db_id>	Cree vistas materializadas que se actualicen automáticamente
refresh_continuous_aggregate_<db_id>	Actualice manualmente los agregados continuos

Para documentación detallada sobre las herramientas de TimescaleDB, consulte TIMESCALEDB_TOOLS.md.

Modo de Herramientas Unificadas

Si conecta muchas bases de datos (5+), la nomenclatura de herramientas por base de datos genera una gran cantidad de herramientas (5 × N). Algunos clientes MCP — Claude en particular — aplican límites estrictos en el número total de herramientas y el tamaño de la descripción de las herramientas que pueden causar que el agente falle al cargar el servidor, ignore las herramientas o se niegue a llamarlas. El problema #18 documenta este síntoma exacto: "el db-mcp-server no funciona correctamente con Claude, aunque funciona bien con OpenAI".

Para estos clientes, inicie el servidor con la bandera --unified-tools para registrar seis herramientas consolidadas (query, execute, transaction, performance, schema, list_databases) en lugar de herramientas por base de datos:

./bin/server -t stdio -c config.json --unified-tools

En modo unificado, cada herramienta acepta un parámetro database requerido que nombra a qué base de datos debe dirigirse la llamada. Consulte la sección Configuración para obtener la lista completa de bases de datos disponibles. Esto reduce drásticamente el número de herramientas y el tamaño acumulado de las descripciones, lo que resuelve los problemas de compatibilidad con Claude.

Para configuraciones muy grandes, también habilite --lazy-loading para que el inicio no abra conexiones a bases de datos que quizás nunca se consulten durante la sesión.

Ejemplos

Consultando Múltiples Bases de Datos

-- Query the MySQL database
query_mysql1("SELECT * FROM users LIMIT 10")

-- Query the PostgreSQL database in the same context
query_postgres1("SELECT * FROM products WHERE price > 100")

-- Query the SQLite database
query_sqlite_app("SELECT * FROM local_data WHERE created_at > datetime('now', '-1 day')")

-- Query the Oracle database
query_oracle_dev("SELECT * FROM employees WHERE hire_date > SYSDATE - 30")

Gestionando Transacciones

-- Start a transaction
transaction_mysql1("BEGIN")

-- Execute statements within the transaction
execute_mysql1("INSERT INTO orders (customer_id, product_id) VALUES (1, 2)")
execute_mysql1("UPDATE inventory SET stock = stock - 1 WHERE product_id = 2")

-- Commit or rollback
transaction_mysql1("COMMIT")
-- OR
transaction_mysql1("ROLLBACK")

Explorando el Esquema de la Base de Datos

-- Get all tables in the database
schema_mysql1("tables")

-- Get columns for a specific table
schema_mysql1("columns", "users")

-- Get constraints
schema_mysql1("constraints", "orders")

Trabajando con Características Específicas de SQLite

-- Create a table in SQLite
execute_sqlite_app("CREATE TABLE IF NOT EXISTS local_cache (key TEXT PRIMARY KEY, value TEXT, timestamp DATETIME)")

-- Use SQLite-specific date functions
query_sqlite_app("SELECT * FROM events WHERE date(created_at) = date('now')")

-- Query SQLite master table for schema information
query_sqlite_app("SELECT name, sql FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'")

-- Performance optimization with WAL mode
execute_sqlite_app("PRAGMA journal_mode = WAL")
execute_sqlite_app("PRAGMA synchronous = NORMAL")

Trabajando con Características Específicas de Oracle

-- Query user tables (excludes system schemas)
query_oracle_dev("SELECT table_name FROM user_tables ORDER BY table_name")

-- Use Oracle-specific date functions
query_oracle_dev("SELECT employee_id, hire_date FROM employees WHERE hire_date >= TRUNC(SYSDATE, 'YEAR')")

-- Oracle sequence operations
execute_oracle_dev("CREATE SEQUENCE emp_seq START WITH 1000 INCREMENT BY 1")
query_oracle_dev("SELECT emp_seq.NEXTVAL FROM DUAL")

-- Oracle-specific data types
query_oracle_dev("SELECT order_id, TO_CHAR(order_date, 'YYYY-MM-DD HH24:MI:SS') FROM orders")

-- Get schema metadata from Oracle data dictionary
query_oracle_dev("SELECT column_name, data_type, nullable FROM user_tab_columns WHERE table_name = 'EMPLOYEES'")

-- Use Oracle analytic functions
query_oracle_dev("SELECT employee_id, salary, RANK() OVER (ORDER BY salary DESC) as salary_rank FROM employees")

Solución de Problemas

Problemas Comunes

• Fallos de Conexión: Verifique la conectividad de red y las credenciales de la base de datos
• Errores de Permisos: Asegúrese de que el usuario de la base de datos tenga los permisos apropiados
• Problemas de Tiempo de Espera: Verifique la configuración de query_timeout en su configuración

Registros

Habilite el registro detallado para la solución de problemas:

./bin/server -t sse -c config.json -v

Pruebas

Ejecutando Pruebas

El proyecto incluye pruebas unitarias y de integración completas para todas las bases de datos soportadas.

Pruebas Unitarias

Ejecute las pruebas unitarias (no se requiere base de datos):

make test
# or
go test -short ./...

Pruebas de Integración

Las pruebas de integración requieren instancias de bases de datos en ejecución. Proporcionamos configuraciones de Docker Compose para una configuración sencilla.

Probar todas las bases de datos:

# Start test databases
docker-compose -f docker-compose.test.yml up -d

# Run all integration tests
go test ./... -v

# Stop test databases
docker-compose -f docker-compose.test.yml down -v

Probar base de datos Oracle:

# Start Oracle test environment
./oracle-test.sh start

# Run Oracle tests
./oracle-test.sh test
# or manually
ORACLE_TEST_HOST=localhost go test -v ./pkg/db -run TestOracle
ORACLE_TEST_HOST=localhost go test -v ./pkg/dbtools -run TestOracle

# Stop Oracle test environment
./oracle-test.sh stop

# Full cleanup (removes volumes)
./oracle-test.sh cleanup

Probar TimescaleDB:

# Start TimescaleDB test environment
./timescaledb-test.sh start

# Run TimescaleDB tests
TIMESCALEDB_TEST_HOST=localhost go test -v ./pkg/db/timescale ./internal/delivery/mcp

# Stop TimescaleDB test environment
./timescaledb-test.sh stop

Pruebas de regresión

Ejecute pruebas de regresión exhaustivas en todos los tipos de bases de datos:

# Ensure all test databases are running
docker-compose -f docker-compose.test.yml up -d
./oracle-test.sh start

# Run regression tests
MYSQL_TEST_HOST=localhost \
POSTGRES_TEST_HOST=localhost \
ORACLE_TEST_HOST=localhost \
go test -v ./pkg/db -run TestRegression

# Run connection pooling tests
go test -v ./pkg/db -run TestConnectionPooling

Integración continua

Todas las pruebas se ejecutan automáticamente en cada pull request mediante GitHub Actions. El pipeline de CI incluye:

• Pruebas unitarias: Pruebas rápidas que no requieren conexiones a bases de datos
• Pruebas de integración: Pruebas contra bases de datos MySQL, PostgreSQL, SQLite y Oracle
• Pruebas de regresión: Pruebas exhaustivas que garantizan la compatibilidad con versiones anteriores
• Linting: Comprobaciones de calidad del código con golangci-lint

Contribuciones

¡Damos la bienvenida a contribuciones al proyecto DB MCP Server! Para contribuir:

1. Haga un fork del repositorio
2. Cree una rama de funcionalidad (git checkout -b feature/amazing-feature)
3. Confirme sus cambios (git commit -m 'feat: add amazing feature')
4. Haga push a la rama (git push origin feature/amazing-feature)
5. Abra un Pull Request

Consulte nuestro archivo CONTRIBUTING.md para obtener pautas detalladas.

Probar sus cambios

Antes de enviar un pull request, asegúrese de:

1. Que todas las pruebas unitarias pasen: go test -short ./...
2. Que las pruebas de integración pasen para las bases de datos afectadas
3. Que el código siga las pautas de estilo del proyecto: golangci-lint run ./...
4. Que las nuevas funcionalidades incluyan una cobertura de pruebas adecuada

Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulte el archivo LICENSE para obtener más detalles.