Servidor de Base de Datos MCP

Una interfaz de razonamiento para bases de datos para agentes de IA compatibles con MCP — no un envoltorio SQL simple.

mcp-database-universal proporciona a los agentes de IA un conjunto de 7 herramientas de razonamiento para explorar y consultar una base de datos de forma segura, comprender su esquema y la forma de los datos, ejecutar preguntas en lenguaje natural y visualizar relaciones — todo sin exponer los detalles internos de la conexión.

Características

• 7 herramientas de razonamiento diseñadas para agentes de IA: probar conexión, listar tablas, inspeccionar una tabla, ejecutar SQL parametrizado, hacer preguntas en lenguaje natural, perfilar datos y renderizar un diagrama ER.

• Multi-motor: SQLite (integrado) más PostgreSQL, MySQL y MSSQL opcionales.

• Seguridad ante todo: solo lectura por defecto, consultas parametrizadas, validación de sentencias, límites de filas/tiempo/salida.

• Salida amigable para LLM: tipos traducidos, NULLs manejados, resultados formateados en tablas Markdown con contexto.

• Introspección de esquema: descubrimiento automático de tablas, columnas, índices, claves foráneas y relaciones.

• Consultas en lenguaje natural: traduce preguntas en texto plano a SQL y devuelve resultados.

Related MCP server: Universal Database MCP Server

Motores compatibles

Instalación

pip install mcp-database-universal

# With optional engines:
pip install "mcp-database-universal[postgres]"
pip install "mcp-database-universal[mysql]"
pip install "mcp-database-universal[mssql]"
# or everything:
pip install "mcp-database-universal[all]"

Inicio rápido

Ejecuta el servidor sobre STDIO (el transporte por defecto para clientes MCP):

DATABASE_URL=sqlite:///app.db python -m mcp_database_universal

URLs de conexión:

sqlite:///path/to/db.db              SQLite (file)
sqlite:///:memory:                   SQLite (in-memory)
postgresql://user:pass@host:5432/db  PostgreSQL
mysql://user:pass@host:3306/db       MySQL
mssql://user:pass@host:1433/db       MSSQL (uses ODBC Driver 18)

Docker

docker build -t mcp-db .

# Mount a SQLite database read-only:
docker run --rm -i \
  -v /host/path/app.db:/data/app.db:ro \
  -e DATABASE_URL=sqlite:////data/app.db \
  mcp-db

# Or in-memory:
docker run --rm -i -e DATABASE_URL=sqlite:///:memory: mcp-db

Configuración

Toda la configuración se realiza mediante variables de entorno.

Herramientas

Ejemplo: query con parámetros

{
  "sql": "SELECT * FROM users WHERE id = :id AND active = :active",
  "params": "{\"id\": 42, \"active\": true}"
}

Los parámetros usan marcadores de posición :name; pasa los valores como una cadena JSON en params.

Ejemplo: natural_query

question: "How many users are there?"
-> SELECT COUNT(*) FROM users
question: "Show me all orders"
-> SELECT * FROM orders LIMIT 100

Un ejemplo funcional contra una pequeña base de datos de muestra está en examples/ junto con fragmentos de configuración listos para usar para clientes MCP comunes.

Configuración de clientes MCP

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "database": {
      "command": "python",
      "args": ["-m", "mcp_database_universal"],
      "env": {"DATABASE_URL": "sqlite:///C:/data/app.db"}
    }
  }
}

Cursor / otros clientes basados en CLI

{
  "mcpServers": {
    "database": {
      "command": "uvx",
      "args": ["mcp-database-universal"],
      "env": {"DATABASE_URL": "sqlite:///C:/data/app.db"}
    }
  }
}

Nota para Windows: el controlador Postgres asíncrono requiere el bucle de eventos selector de Windows. El paquete establece esta política automáticamente en win32, por lo que no se necesita configuración adicional.

Desarrollo

pip install -e ".[dev]"
pytest

Las pruebas de integración para PostgreSQL/MySQL usan Docker Compose y se omiten automáticamente si los servidores no son accesibles:

docker compose -f tests/integration/docker-compose.yml up -d
pytest

Modelo de seguridad

• El servidor es de solo lectura por defecto; INSERT/UPDATE/DELETE/DROP/ALTER y otras sentencias de escritura están bloqueadas.

• Las escrituras solo son posibles cuando el operador establece explícitamente DATABASE_READ_ONLY=false y DATABASE_WRITE_ENABLED=true.

• Los resultados de las consultas están limitados por recuento de filas, tiempo de espera y tamaño de salida — se previenen consultas descontroladas.

Licencia

MIT