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.

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 performance

Arquitectura 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 : El montaje se realiza en /app/my-config.json porque el contenedor ya tiene un archivo en /app/config.json . Si encuentra advertencias de incompatibilidad de plataforma, puede especificar la plataforma: --platform linux/amd64 o --platform linux/arm64 .

De 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
./server -t sse -c config.json

Ejecució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.json

La 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.json

Conecte 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
      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 down

Asegú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"
    },
    {
      "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 stdio

Herramientas 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_mysql1
execute_mysql1
transaction_mysql1
schema_mysql1
performance_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.json
Herramienta 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.json
- Anular el punto de entrada: --entrypoint /app/server freepeak/db-mcp-server -t sse -c /app/my-config.json
- Utilice 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.sh
- Verifique 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.json

Contribuyendo

¡Agradecemos tus contribuciones! Puedes ayudarnos de la siguiente manera:

Bifurcar el repositorio
Crear una rama de características: git checkout -b new-feature
Confirme sus cambios: git commit -am 'Add new feature'
Empujar a la rama: git push origin new-feature
Enviar 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_databases

Consultando la base de datos :

mcp_multidb_query_mysql1
Query: SELECT * FROM users LIMIT 10

Visualización del esquema de la base de datos :

mcp_multidb_schema_mysql1

Ejecució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: begin

Solució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 API
SDK de OpenAI Agents instalado: pip install openai-agents
Una 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 API

Probando 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.sh

El 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

Integrations

Servidor MCP de múltiples bases de datos

¿Qué es DB MCP Server?

Conceptos básicos

Compatibilidad con múltiples bases de datos

Generación dinámica de herramientas

Arquitectura limpia

Características

Bases de datos compatibles actualmente

Inicio rápido

Usando Docker

De la fuente

Ejecución del servidor

Modo STDIO (para integración IDE)

Modo SSE (eventos enviados por el servidor)

Docker Compose

Configuración

Configuración de la base de datos

Opciones de la línea de comandos

Herramientas disponibles

Convención de nomenclatura de herramientas

Herramientas específicas de la base de datos

Herramientas globales

Ejemplos

Consulta de múltiples bases de datos

Ejecución de transacciones

Hoja de ruta

T3 2025

cuarto trimestre de 2025

2026

Solución de problemas

Problemas comunes

Registros

Contribuyendo

Licencia

Soporte y contacto

Integración del cursor

Convención de nomenclatura de herramientas

Configuración del cursor

Uso de herramientas MCP en el cursor

Ejemplos:

Solución de problemas de las herramientas MCP en Cursor

Integración del SDK de agentes de OpenAI

Prerrequisitos

Ejemplo básico de integración

Probando su integración

Solución de problemas de integración del SDK de agentes

Historia de las estrellas

Appeared in Searches