SQL MCP Server

Un servidor Model Context Protocol que expone una base de datos Postgres a agentes LLM (Claude Desktop, Claude Code o cualquier cliente MCP) a través de seis herramientas de solo lectura. Apunta un agente a él y haz preguntas como "¿qué clientes realizaron más de cinco pedidos el mes pasado?" — el agente explora el esquema y consulta los datos por sí mismo, a través de las herramientas siguientes.

Herramientas

Related MCP server: mcp-data-gateway

Por qué esto no es "solo un envoltorio de psycopg2"

Las demostraciones de texto a SQL son habituales; la parte realmente difícil — y donde este proyecto pone su esfuerzo — es hacer que execute_select sea seguro para entregarlo a un LLM que generará SQL arbitrario:

1. Rol de Postgres de solo lectura. El servidor se conecta como mcp_readonly, un rol con permisos de solo SELECT (ver scripts/init_schema.sql). Ni siquiera un error en las comprobaciones a nivel de aplicación que se indican a continuación puede provocar una escritura.

2. Aplicación de solo lectura a nivel de sesión. Cada conexión ejecuta SET TRANSACTION READ ONLY (db.py).

3. Validación de sentencias (security.py): solo se permite una única sentencia SELECT/WITH — sin sentencias apiladas (; DROP TABLE ...), sin comentarios SQL (bloquea el contrabando de sentencias a través de comentarios) y una lista negra de palabras clave cubre INSERT/UPDATE/DELETE/DDL/GRANT/etc., incluido SELECT ... INTO (que crea una tabla silenciosamente).

4. Validación de identificadores. describe_table, sample_rows y count_rows reciben un nombre de tabla como parámetro. Dado que los identificadores SQL no se pueden parametrizar con marcadores de posición, los nombres de tabla se comprueban contra una regex estricta y una lista blanca dinámica obtenida de information_schema — no solo mediante el escape de cadenas.

5. Límites de recursos. Un statement_timeout de Postgres evita consultas descontroladas y se aplica un tope de filas del lado del servidor a cada resultado de consulta, incluso si la consulta del LLM no especificó un LIMIT.

Inicio rápido

git clone <this-repo>
cd sql-mcp-server
pip install -r requirements.txt

# 1. Start Postgres with the sample schema
docker compose up -d

# 2. Generate sample e-commerce data (uses the postgres superuser, not mcp_readonly)
PGUSER=postgres PGPASSWORD=postgres python scripts/generate_sample_data.py

# 3. Configure the server to use the read-only role
cp .env.example .env
# edit .env if you changed the default mcp_readonly password

# 4. Run the tests
pytest

# 5. Run the server (stdio transport, for use with an MCP client)
python -m sql_mcp_server.server

Conexión con Claude Desktop

Añádelo a tu configuración MCP de Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "sql-explorer": {
      "command": "python",
      "args": ["-m", "sql_mcp_server.server"],
      "cwd": "/absolute/path/to/sql-mcp-server",
      "env": {
        "PGHOST": "localhost",
        "PGPORT": "5432",
        "PGDATABASE": "sales",
        "PGUSER": "mcp_readonly",
        "PGPASSWORD": "change_me"
      }
    }
  }
}

Reinicia Claude Desktop y luego pregunta algo como "¿Qué tablas están disponibles y qué categoría de producto tiene los mayores ingresos totales?"

Esquema de ejemplo

orders → order_items → products → categories, además de customers. Los ingresos de un pedido = sum(order_items.quantity * order_items.unit_price). El generador siembra ~600 clientes, ~3.500 pedidos y un puñado de peculiaridades intencionadas en los datos (correos electrónicos faltantes, algunos pedidos atípicos al por mayor) para que las consultas parezcan tratar con datos reales.

Pruebas

tests/test_security.py y tests/test_tools.py se ejecutan sin base de datos — prueban directamente la capa de validación y las funciones de las herramientas con la capa de BD simulada. Esto es lo que ejecuta CI. db.py en sí mismo (la capa de psycopg2) se pone a prueba en la práctica ejecutando el servidor contra la instancia de Postgres de Docker; consulta Inicio rápido más arriba.

Estructura del proyecto

sql_mcp_server/
  config.py    Environment-based settings
  security.py  SQL/identifier validation (the core safety logic)
  db.py        psycopg2 access layer
  server.py    MCP tool definitions
scripts/
  init_schema.sql            Schema + read-only role setup
  generate_sample_data.py    Faker-based sample data
tests/
  test_security.py  Validation logic (18+ cases: injection, stacked
                     statements, comment smuggling, DDL/DML blocking, etc.)
  test_tools.py     Tool functions with mocked DB