mcp-sql-server

Servidor MCP (Model Context Protocol) genérico de solo lectura sobre bases de datos SQL (SQLite o PostgreSQL), construido con el SDK oficial de Python (mcp) y SQLAlchemy.

Es la evolución natural de sql_tools.py del proyecto Marvel Intelligence Assistant: la misma lógica de guardrails (solo SELECT, whitelist de tablas, LIMIT forzado, timeout), pero expuesta como servidor MCP estándar en vez de LangChain StructuredTools — lo que significa que puede ser usado no solo por ese proyecto, sino por Claude Desktop, Claude Code o cualquier otro cliente compatible con MCP, sin reescribir nada.

Tools expuestas

Tool	Descripción
list_tables	Lista las tablas disponibles (respetando whitelist si está configurada)
describe_table(table_name)	Devuelve columnas y tipos de una tabla
run_query(sql, limit)	Ejecuta un SELECT de solo lectura y devuelve resultado en tabla

Guardrails aplicados

1. Solo se permiten sentencias SELECT (bloquea INSERT/UPDATE/DELETE/DROP/ALTER/etc.)
2. No se permiten múltiples sentencias en una misma query
3. Whitelist opcional de tablas accesibles vía ALLOWED_TABLES
4. LIMIT forzado si el usuario no lo especifica (con tope máximo configurable)
5. Timeout de ejecución por query

Instalación

python -m venv venv
# Windows: venv\Scripts\activate
source venv/bin/activate
pip install -r requirements.txt

Configuración (variables de entorno)

Variable	Descripción	Por defecto
DB_URL	Cadena de conexión SQLAlchemy	sqlite:///./marvel.db
ALLOWED_TABLES	Tablas permitidas, separadas por coma	todas
QUERY_TIMEOUT_S	Timeout por query (segundos)	10
DEFAULT_LIMIT	Límite de filas por defecto	50
MAX_LIMIT	Límite máximo de filas	500

Ejemplos de DB_URL:

• SQLite: sqlite:///C:/ruta/a/marvel.db
• PostgreSQL: postgresql+psycopg2://usuario:password@localhost:5432/mi_bd

Probar contra tu marvel.db real

export DB_URL="sqlite:///C:/ruta/a/tu/marvel.db"   # Windows: usa la sintaxis de tu shell
python server.py

Conectarlo a Claude Desktop

Añade esto a tu claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "sql-readonly": {
      "command": "C:\\ruta\\a\\mcp-sql-server\\venv\\Scripts\\python.exe",
      "args": ["C:\\ruta\\a\\mcp-sql-server\\server.py"],
      "env": {
        "DB_URL": "sqlite:///C:/ruta/a/marvel.db"
      }
    }
  }
}

Reinicia Claude Desktop y podrás preguntarle directamente sobre tu base de datos ("¿qué tablas hay?", "dime las 5 películas con más ingresos") usando estas tools.

Relación con Marvel Intelligence Assistant

Este servidor reutiliza el mismo diseño de guardrails que sql_guardrails.py del proyecto Marvel, pero desacoplado del router de LangChain. La idea de portfolio es poder decir:

"Mi SQL agent en Marvel Intelligence Assistant usa LangChain StructuredTools de forma nativa. Además, construí una versión de esas mismas herramientas como servidor MCP independiente, reutilizable desde cualquier cliente compatible (Claude Desktop, Claude Code, u otros agentes), no solo desde mi router."

Reutilización en otros proyectos (n8n + MCP + RAG)

Este mismo servidor (apuntando a otra BBDD en vez de Marvel) es la pieza de "datos estructurados en vivo" de otro proyecto combinado más adelante: n8n dispara el flujo, el agente usa este MCP para consultar datos en tiempo real, y un componente RAG aporta el contexto documental (informes técnicos, normativa) para el análisis final.