Servidor MCP de múltiples bases de datos
¿Qué es DB MCP Server?
El servidor DB MCP proporciona una forma estandarizada para que los modelos de IA interactúen con múltiples bases de datos simultáneamente. Basado en 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 mediante una interfaz unificada.
Related MCP server: MCP Server
Conceptos básicos
Compatibilidad con múltiples bases de datos
A diferencia de los conectores de bases de datos tradicionales, DB MCP Server puede conectarse e interactuar con múltiples bases de datos simultáneamente:
{
"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"
}
]
}Generación dinámica de herramientas
Para cada base de datos conectada, el servidor genera automáticamente un conjunto de 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 performanceArquitectura limpia
El servidor sigue los principios de Arquitectura Limpia con estas capas:
Capa de dominio : entidades y interfaces empresariales principales
Capa de repositorio : Implementaciones de acceso a datos
Capa de caso de uso : lógica empresarial de la aplicación
Capa de entrega : Interfaces externas (herramientas MCP)
Características
Compatibilidad simultánea con múltiples bases de datos : conéctese e interactúe con múltiples bases de datos MySQL y PostgreSQL simultáneamente
Generación de herramientas específicas de la base de datos : crea automáticamente herramientas especializadas para cada base de datos conectada
Arquitectura limpia : diseño modular con clara separación de preocupaciones
Compatibilidad del SDK de OpenAI Agents : compatibilidad total con el SDK de OpenAI Agents para una integración perfecta con asistentes de IA
Herramientas de bases de datos dinámicas :
Ejecutar consultas SQL con parámetros
Ejecute declaraciones de modificación de datos con un manejo de errores adecuado
Administrar transacciones de bases de datos entre sesiones
Explorar esquemas y relaciones de bases de datos
Analice el rendimiento de las consultas y reciba sugerencias de optimización
Interfaz unificada : patrones de interacción consistentes en diferentes tipos de bases de datos
Gestión de conexiones : configuración sencilla para múltiples conexiones de bases de datos
Bases de datos compatibles actualmente
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 |
Inicio rápido
Usando Docker
La forma más rápida de comenzar es con Docker:
# Pull the latest image
docker pull freepeak/db-mcp-server:latest
# Option 1: Run with environment variables (recommended)
docker run -p 9092:9092 \
-v $(pwd)/config.json:/app/my-config.json \
-e TRANSPORT_MODE=sse \
-e CONFIG_PATH=/app/my-config.json \
freepeak/db-mcp-server
# Option 2: Override the entrypoint
docker run -p 9092:9092 \
-v $(pwd)/config.json:/app/my-config.json \
--entrypoint /app/server \
freepeak/db-mcp-server \
-t sse -c /app/my-config.json
# Option 3: Use shell to execute the command
docker run -p 9092:9092 \
-v $(pwd)/config.json:/app/my-config.json \
freepeak/db-mcp-server \
/bin/sh -c "/app/server -t sse -c /app/my-config.json"Nota : Montamos en
/app/my-config.jsonporque el contenedor ya tiene un archivo en/app/config.json.
Soporte de plataforma
La imagen de Docker admite múltiples plataformas:
linux/amd64- Para sistemas basados en Intel/AMD (la mayoría de los servidores y computadoras de escritorio Linux/Windows)linux/arm64- Para sistemas basados en ARM64 (Mac con Apple Silicon, servidores ARM)
Si encuentra errores de incompatibilidad de plataforma (por ejemplo, "La plataforma de la imagen solicitada no coincide con la plataforma del host detectada"), especifique la plataforma explícitamente:
# For Intel/AMD (x86_64) systems
docker run --platform linux/amd64 -p 9092:9092 freepeak/db-mcp-server
# For ARM64 systems (like Apple Silicon Macs)
docker run --platform linux/arm64 -p 9092:9092 freepeak/db-mcp-serverDe la 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 in SSE mode
./bin/server -t sse -c config.jsonEjecución del servidor
El servidor admite múltiples modos de transporte para adaptarse a diferentes casos de uso:
Modo STDIO (para integración IDE)
Ideal para la integración con asistentes de codificación de IA:
# Run the server in STDIO mode
./server -t stdio -c config.jsonLa salida se enviará como mensajes JSON-RPC a stdout, mientras que los registros van a stderr.
Para la integración del cursor, agregue esto a su .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)
Para aplicaciones y servicios basados en web:
# Run with default host (localhost) and port (9092)
./server -t sse -c config.json
# Specify a custom host and port
./server -t sse -host 0.0.0.0 -port 8080 -c config.jsonConecte su cliente a http://localhost:9092/sse para la transmisión de eventos.
Docker Compose
Para entornos de desarrollo con contenedores de bases de datos, proporcionamos un archivo docker-compose.yml completo:
services:
db-mcp-server:
image: freepeak/db-mcp-server:latest
ports:
- "9092:9092"
volumes:
- ./config.json:/app/config.json
- ./wait-for-it.sh:/app/wait-for-it.sh
command:
[
"/bin/sh",
"-c",
"chmod +x /app/wait-for-it.sh && /app/wait-for-it.sh mysql1:3306 -t 60 && /app/wait-for-it.sh mysql2:3306 -t 60 && /app/wait-for-it.sh postgres1:5432 -t 60 && /app/wait-for-it.sh postgres3:5432 -t 60 && /app/server -t sse -c /app/config.json",
]
depends_on:
mysql1:
condition: service_healthy
mysql2:
condition: service_healthy
postgres1:
condition: service_healthy
postgres2:
condition: service_healthy
postgres3:
condition: service_healthy
mysql1:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: password
MYSQL_DATABASE: db1
MYSQL_USER: user1
MYSQL_PASSWORD: password1
MYSQL_AUTHENTICATION_PLUGIN: mysql_native_password
ports:
- "13306:3306"
volumes:
- mysql1_data:/var/lib/mysql
command: --default-authentication-plugin=mysql_native_password --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
healthcheck:
test:
[
"CMD",
"mysqladmin",
"ping",
"-h",
"localhost",
"-u",
"root",
"-ppassword",
]
interval: 5s
timeout: 5s
retries: 10
mysql2:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: password
MYSQL_DATABASE: db2
MYSQL_USER: user2
MYSQL_PASSWORD: password2
MYSQL_AUTHENTICATION_PLUGIN: mysql_native_password
ports:
- "13307:3306"
volumes:
- mysql2_data:/var/lib/mysql
command: --default-authentication-plugin=mysql_native_password --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
healthcheck:
test:
[
"CMD",
"mysqladmin",
"ping",
"-h",
"localhost",
"-u",
"root",
"-ppassword",
]
interval: 5s
timeout: 5s
retries: 10
postgres1:
image: postgres:15
environment:
POSTGRES_USER: user1
POSTGRES_PASSWORD: password1
POSTGRES_DB: db1
ports:
- "15432:5432"
volumes:
- postgres1_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U user1 -d db1"]
interval: 5s
timeout: 5s
retries: 10
postgres2:
image: postgres:17
environment:
POSTGRES_USER: user2
POSTGRES_PASSWORD: password2
POSTGRES_DB: db2
ports:
- "15433:5432"
volumes:
- postgres2_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U user2 -d db2"]
interval: 5s
timeout: 5s
retries: 10
postgres3:
image: postgres:16.3-alpine
environment:
POSTGRES_USER: screener
POSTGRES_PASSWORD: screenerpass
POSTGRES_DB: screenerdb
ports:
- "15434:5432"
volumes:
- postgres_screener_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U screener -d screenerdb"]
interval: 5s
timeout: 5s
retries: 10
volumes:
mysql1_data:
mysql2_data:
postgres1_data:
postgres2_data:
postgres_screener_data:Características principales de esta configuración de docker-compose:
El contenedor db-mcp-server espera a que todos los servicios de base de datos estén listos antes de iniciarse
Se incluyen varios tipos y versiones de bases de datos (MySQL 8.0, PostgreSQL 15, 16.3 y 17)
Todas las bases de datos incluyen controles de estado para garantizar que estén completamente inicializadas antes de que el servidor se conecte.
Volúmenes persistentes para todos los servicios de base de datos
Puertos expuestos para acceso directo a la base de datos si es necesario
La configuración utiliza un script wait-for-it.sh para garantizar que todos los servicios de la base de datos estén listos antes de iniciar el servidor. Este script comprueba si hay un host o puerto TCP disponible antes de continuar. Debe incluir este script en el directorio de su proyecto. La configuración de Docker monta este script en el contenedor y lo utiliza para verificar la disponibilidad de la base de datos.
Para utilizar esta configuración:
# Start all services
docker-compose up -d
# Check logs
docker-compose logs -f db-mcp-server
# Stop all services
docker-compose downAsegúrese de que su archivo config.json incluya detalles de conexión que coincidan con los servicios definidos en docker-compose.yml.
Configuración
Configuración de la base de datos
Crea un archivo config.json con tus conexiones de base 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": "mysql2",
"type": "mysql",
"host": "mysql2",
"port": 3306,
"name": "db2",
"user": "user2",
"password": "password2"
},
{
"id": "postgres1",
"type": "postgres",
"host": "postgres1",
"port": 5432,
"name": "db1",
"user": "user1",
"password": "password1"
},
{
"id": "postgres2",
"type": "postgres",
"host": "postgres2",
"port": 5432,
"name": "db2",
"user": "user2",
"password": "password2"
},
{
"id": "postgres3",
"type": "postgres",
"host": "postgres3",
"port": 5432,
"name": "screenerdb",
"user": "screener",
"password": "screenerpass"
}
]
}Al utilizar la configuración docker-compose, tenga en cuenta que los valores host deben coincidir con los nombres de servicio en el archivo docker-compose.yml.
Opciones de la línea de comandos
El servidor admite varias opciones de línea de comandos:
# Basic options
./server -t <transport> -c <config-file>
# Available transports: stdio, sse
# For SSE transport, additional options:
./server -t sse -host <hostname> -port <port> -c <config-file>
# Direct database configuration:
./server -t stdio -db-config '{"connections":[...]}'
# Environment variable configuration:
export DB_CONFIG='{"connections":[...]}'
./server -t stdioHerramientas disponibles
Para cada base de datos conectada (por ejemplo, "mysql1", "mysql2"), el servidor crea:
Convención de nomenclatura de herramientas
El servidor genera automáticamente herramientas con nombres que siguen este formato:
<tool_type>_<database_id>Dónde:
<tool_type>: Uno de: consulta, ejecución, transacción, esquema, rendimiento<database_id>: El ID de la base de datos tal como se define en su configuración
Ejemplos de nombres de herramientas para una base de datos con ID "mysql1":
query_mysql1execute_mysql1transaction_mysql1schema_mysql1performance_mysql1
Herramientas específicas de la base de datos
query_<dbid>: Ejecutar consultas SQL en la base de datos especificada{ "query": "SELECT * FROM users WHERE age > ?", "params": [30] }execute_<dbid>: Ejecutar sentencias SQL (INSERTAR, ACTUALIZAR, ELIMINAR){ "statement": "INSERT INTO users (name, email) VALUES (?, ?)", "params": ["John Doe", "john@example.com"] }transaction_<dbid>: Administrar transacciones de base de datos// Begin transaction { "action": "begin", "readOnly": false } // Execute within transaction { "action": "execute", "transactionId": "<from begin response>", "statement": "UPDATE users SET active = ? WHERE id = ?", "params": [true, 42] } // Commit transaction { "action": "commit", "transactionId": "<from begin response>" }schema_<dbid>: Obtener información del esquema de la base de datos{ "random_string": "dummy" }performance_<dbid>: Analizar el rendimiento de las consultas{ "action": "analyzeQuery", "query": "SELECT * FROM users WHERE name LIKE ?" }
Herramientas globales
list_databases: enumera todas las conexiones de base de datos configuradas{}
Ejemplos
Consulta de múltiples bases de datos
// Query the first database
{
"name": "query_mysql1",
"parameters": {
"query": "SELECT * FROM users LIMIT 5"
}
}
// Query the second database
{
"name": "query_mysql2",
"parameters": {
"query": "SELECT * FROM products LIMIT 5"
}
}Ejecución de transacciones
// Begin transaction
{
"name": "transaction_mysql1",
"parameters": {
"action": "begin"
}
}
// Response contains transactionId
// Execute within transaction
{
"name": "transaction_mysql1",
"parameters": {
"action": "execute",
"transactionId": "tx_12345",
"statement": "INSERT INTO orders (user_id, product_id) VALUES (?, ?)",
"params": [1, 2]
}
}
// Commit transaction
{
"name": "transaction_mysql1",
"parameters": {
"action": "commit",
"transactionId": "tx_12345"
}
}Hoja de ruta
Nos comprometemos a ampliar DB MCP Server para admitir una amplia gama de sistemas de bases de datos:
T3 2025
MongoDB : soporte para operaciones de bases de datos orientadas a documentos
SQLite : Integración ligera de bases de datos integradas
MariaDB : paridad de funciones completa con la implementación de MySQL
cuarto trimestre de 2025
Microsoft SQL Server : compatibilidad con bases de datos empresariales con capacidades T-SQL
Oracle Database : integración de nivel empresarial
Redis - Operaciones de almacenamiento de clave-valor
2026
Cassandra - Soporte para bases de datos NoSQL distribuidas
Elasticsearch : capacidades especializadas de búsqueda y análisis
CockroachDB : base de datos SQL distribuida para aplicaciones a escala global
DynamoDB : integración de bases de datos NoSQL nativas de AWS
Neo4j - Compatibilidad con bases de datos gráficas
ClickHouse - Soporte de bases de datos analíticas
Solución de problemas
Problemas comunes
Errores de conexión : Verifique la configuración de conexión de su base de datos en
config.jsonHerramienta no encontrada : asegúrese de que el servidor esté en ejecución y verifique los prefijos del nombre de la herramienta
Consultas fallidas : Verifique la sintaxis SQL y los permisos de la base de datos
Errores de montaje de volumen de Docker : Si ves errores como
mountpoint for /app/config.json: not a directory, significa que el contenedor ya tiene un archivo en esa ruta. Móntalo en una ruta diferente (p. ej.,/app/my-config.json) y actualiza tu configuración según corresponda.Errores de comandos de Docker : si encuentra errores relacionados con los comandos de Docker, utilice uno de estos enfoques:
Utilice variables de entorno:
-e TRANSPORT_MODE=sse -e CONFIG_PATH=/app/my-config.jsonAnular el punto de entrada:
--entrypoint /app/server freepeak/db-mcp-server -t sse -c /app/my-config.jsonUtilice la ejecución del shell:
freepeak/db-mcp-server /bin/sh -c "/app/server -t sse -c /app/my-config.json"
Wait-for-it.sh falta o no funciona : si ve errores relacionados con wait-for-it.sh:
Asegúrese de que el archivo exista en el directorio de su proyecto
Asegúrese de que tenga permisos ejecutables:
chmod +x wait-for-it.shVerifique que los finales de línea sean correctos (use LF estilo Unix, no CRLF estilo Windows)
Si aún tiene problemas, puede modificar docker-compose.yml para usar comprobaciones del estado del servicio en su lugar.
Registros
El servidor escribe registros en:
Modo STDIO: stderr
Modo SSE: stdout y
./logs/db-mcp-server.log
Habilite el registro de depuración con el indicador -debug :
./server -t sse -debug -c config.jsonContribuyendo
¡Agradecemos tus contribuciones! Puedes ayudarnos de la siguiente manera:
Bifurcar el repositorio
Crear una rama de características:
git checkout -b new-featureConfirme sus cambios:
git commit -am 'Add new feature'Empujar a la rama:
git push origin new-featureEnviar una solicitud de extracción
Asegúrese de que su código cumpla con nuestros estándares de codificación e incluya pruebas adecuadas.
Licencia
Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.
Soporte y contacto
Para preguntas o problemas, envíe un correo electrónico a mnhatlinh.doan@gmail.com
Abrir un problema directamente: Rastreador de problemas
Si DB MCP Server ayuda en su trabajo, considere brindar soporte a:
Integración del cursor
Convención de nomenclatura de herramientas
El servidor MCP registra herramientas con nombres que coinciden con el formato que Cursor espera. Los nombres de las herramientas siguen este formato:
mcp_<servername>_<tooltype>_<dbID>Por ejemplo: mcp_mysql1_db_mcp_server_stdio_schema_mysql1_db
El servidor utiliza el nombre mysql1_db_mcp_server_stdio de forma predeterminada, que debe coincidir con la configuración del cursor en el archivo mcp.json .
Configuración del cursor
En la configuración de tu Cursor ( ~/.cursor/mcp.json ), deberías tener una configuración como:
{
"mcpServers": {
"multidb": {
"command": "/path/to/db-mcp-server/server",
"args": ["-t", "stdio", "-c", "/path/to/database_config.json"]
}
}
}El servidor registrará automáticamente herramientas con nombres simples que coincidan con los identificadores de base de datos en su configuración.
Uso de herramientas MCP en el cursor
Una vez que su servidor MCP de base de datos esté en funcionamiento y configurado correctamente en Cursor, podrá usar las herramientas MCP en las conversaciones de su asistente de IA. Las herramientas siguen este patrón de nombres:
mcp_<server_name>_<tool_type>_<database_id>Dónde:
<server_name>es el nombre definido en su .cursor/mcp.json (por ejemplo, "multidb")<tool_type>es uno de los siguientes: consulta, ejecución, transacción, esquema, rendimiento, lista_bases_de_datos<database_id>es el ID de la base de datos de su configuración (no es necesario para list_databases)
Ejemplos:
Para un servidor llamado "multidb" con un ID de base de datos "mysql1":
Listado de todas las bases de datos :
mcp_multidb_list_databasesConsultando la base de datos :
mcp_multidb_query_mysql1
Query: SELECT * FROM users LIMIT 10Visualización del esquema de la base de datos :
mcp_multidb_schema_mysql1Ejecución de sentencias :
mcp_multidb_execute_mysql1
Statement: INSERT INTO users (name, email) VALUES ('John Doe', 'john@example.com')Gestión de transacciones :
mcp_multidb_transaction_mysql1
Action: beginSolución de problemas de las herramientas MCP en Cursor
Si el asistente de IA no puede llamar a las herramientas MCP:
Asegúrese de que el servidor esté ejecutándose (verifique con
ps aux | grep server)Verifique que su configuración de .cursor/mcp.json sea correcta
Asegúrese de que el nombre_del_servidor en .env coincida con lo que hay en las llamadas de su herramienta MCP
Reiniciar el cursor después de realizar cambios de configuración
Verifique los registros en el directorio logs/ para ver si hay errores
Integración del SDK de agentes de OpenAI
El servidor DB MCP es totalmente compatible con el SDK de agentes de OpenAI, lo que le permite crear agentes de IA que pueden interactuar con bases de datos directamente.
Prerrequisitos
Cuenta OpenAI con acceso a la API
SDK de OpenAI Agents instalado:
pip install openai-agentsUna instancia de servidor DB MCP en ejecución (modo SSE)
Ejemplo básico de integración
A continuación se explica cómo integrar el servidor DB MCP con un agente OpenAI:
from openai import OpenAI
from agents.agent import Agent, ModelSettings
from agents.tools.mcp_server import MCPServerSse, MCPServerSseParams
# Connect to the MCP server
db_server = MCPServerSse(
params=MCPServerSseParams(
url="http://localhost:9095/sse", # URL to your running DB MCP server
schema={
"params": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {"type": "string"},
"description": {"type": "string"},
"parameters": {"type": "object"}
}
}
}
}
),
)
# Create the agent with access to database tools
agent = Agent(
name="Database Agent",
model="gpt-4o",
model_settings=ModelSettings(temperature=0.1),
instructions="""
You are a database helper agent. You can execute SQL queries,
manage database transactions, and explore schema information.
""",
mcp_servers=[db_server],
)
# Now the agent can be used to interact with your databases through the OpenAI APIProbando su integración
El repositorio incluye un script de prueba para verificar la compatibilidad con el SDK de OpenAI Agents:
# Run the test script
./test_tools/openai-agent-sdk-test/run_test.shEl guión hará lo siguiente:
Construya el servidor con los últimos cambios
Inicie el servidor si aún no está en ejecución
Pruebe la conexión con el SDK de OpenAI Agents
Informar si la integración está funcionando correctamente
Solución de problemas de integración del SDK de agentes
Si encuentra problemas:
Asegúrese de que el servidor se esté ejecutando en modo SSE en el puerto esperado
Compruebe que su clave API de OpenAI esté configurada como una variable de entorno
Verifique que las instrucciones de su agente mencionen específicamente las herramientas de base de datos
Inspeccione los registros del servidor para detectar cualquier mensaje de error
Historia de las estrellas
Configuración del tiempo de espera de la consulta de la base de datos
Puede configurar el tiempo de espera de la consulta de base de datos para cada conexión en el archivo config.json . El tiempo de espera se especifica en segundos.
Ejemplo de configuración:
{
"connections": [
{
"id": "mysql1",
"type": "mysql",
"host": "mysql1",
"port": 3306,
"name": "db1",
"user": "user1",
"password": "password1",
"query_timeout": 60, // 60 seconds timeout for queries
"max_open_conns": 20,
"max_idle_conns": 5,
"conn_max_lifetime_seconds": 300,
"conn_max_idle_time_seconds": 60
}
]
}Si no se especifica, el tiempo de espera predeterminado para las consultas es de 30 segundos. Puede anular este tiempo de espera para consultas individuales especificando el parámetro de timeout (en milisegundos) al ejecutar una consulta.
{
"tool": "query_mysql",
"params": {
"query": "SELECT * FROM large_table",
"database": "mysql1",
"timeout": 120000 // 120 seconds (overrides the database configuration)
}
}