mcp-sqlserver

Utilidad de solo lectura para consultar una base de datos SQL Server desde un servidor MCP (Claude Code / Claude Desktop) y/o desde la terminal mediante una skill de Claude Code.

Es el equivalente para SQL Server de homemade-mcp-oracle-database-10g-claude: misma arquitectura, adaptada a T-SQL y a pyodbc.

Diferencias respecto a la versión Oracle

Related MCP server: sql-explorer-mcp

Arquitectura

src/
  config.py           Carga y valida .env (conexión, driver, política)
  db.py               Conexión pyodbc; autodetecta el driver; nunca hace commit (rollback al cerrar)
  sql_guard.py        Guard de solo lectura para T-SQL
  audit_log.py        Auditoría (logs/query_audit.log)
  query_runner.py     Ejecuta SQL con límite de filas, timeout y auditoría; resultado JSON-safe
  schema_inspector.py list_databases / list_tables / describe_table (con marca de PK)
  mcp_server.py       Servidor MCP (stdio)

scripts/
  install.py          Instalador (venv, deps, .env, mcp-config.json, registro en Claude Code)
  test_connection.py  Prueba mínima de conectividad
  query.py            CLI de consultas (lo usa también la skill)

tests/test_sql_guard.py            Tests del guard (no requieren SQL Server)
.claude/skills/sqlserver-query/    Skill de Claude Code

Modelo de seguridad (defensa en profundidad)

1. Base de datos (barrera real): usa un login con permisos de solo lectura (db_datareader, o SELECT sobre lo necesario). Nada de lo siguiente lo reemplaza.

2. Guard de software (src/sql_guard.py): T-SQL permite cosas que otros dialectos no, así que el guard enmascara comentarios, literales e identificadores y luego busca palabras prohibidas en todo el texto:

   • sentencias sin ; (SELECT 1 DELETE FROM t es válido en T-SQL),

   • SELECT … INTO (crea tablas), WITH cte AS (…) DELETE/UPDATE/MERGE,

   • EXEC, DECLARE, SET, USE, WAITFOR, OPENROWSET/OPENQUERY, NEXT VALUE FOR, xp_*, DDL, permisos… Un ; o DELETE dentro de un literal ('a; DELETE') no da falso positivo. Ante la duda (literal sin cerrar, etc.) rechaza.

3. Transacción nunca confirmada: la conexión es sin autocommit y se hace rollback al cerrar; además se declara ApplicationIntent=ReadOnly.

4. Límites: MAX_ROWS (resultado marcado truncated) y QUERY_TIMEOUT_SECONDS.

5. Auditoría: toda ejecución (OK, error o rechazada) en logs/query_audit.log.

Instalación

install.bat                      # Windows
python scripts/install.py        # cualquier SO

Crea .venv, instala dependencias, copia .env.example a .env, genera mcp-config.json y registra el servidor en Claude Code (--no-register para omitirlo, --force para rehacerlo). Luego edita .env.

Requisito del sistema: un ODBC Driver for SQL Server (17 o 18) instalado. Si no lo tienes: https://learn.microsoft.com/sql/connect/odbc/download-odbc-driver-for-sql-server.

Configuración (.env)

MSSQL_HOST=servidor        MSSQL_PORT=1433        MSSQL_INSTANCE=   # p. ej. SQLEXPRESS
MSSQL_DATABASE=MiBase
MSSQL_USER=lector          MSSQL_PASSWORD=...     # o MSSQL_TRUSTED_CONNECTION=true

Con MSSQL_INSTANCE se conecta a HOST\INSTANCIA (SQL Browser resuelve el puerto). MSSQL_TRUST_SERVER_CERTIFICATE=true (por defecto) cubre certificados autofirmados, habituales en servidores legacy; ponlo en false si tu servidor tiene un certificado válido. Nunca subas .env a un repositorio.

Uso

.venv\Scripts\python scripts\test_connection.py
.venv\Scripts\python scripts\query.py "SELECT TOP 10 * FROM dbo.mi_tabla" --format json
.venv\Scripts\python scripts\query.py --file consulta.sql
.venv\Scripts\python -m unittest discover -s tests -v

Servidor MCP

Registro manual en Claude Code:

claude mcp add sqlserver -s user -- "<ruta>\.venv\Scripts\python.exe" "<ruta>\src\mcp_server.py"

Para otro cliente, usa mcp-config.json (lo genera el instalador; ver mcp-config.example.json). Se invoca el archivo directamente y no con -m src.mcp_server porque un cliente MCP lanza el proceso con un cwd que no controlas; mcp_server.py ajusta sys.path con su propia ubicación y config.py busca .env junto al proyecto.

Tools:

• run_query(sql) — SELECT / WITH … SELECT, con guard.

• list_databases() — bases accesibles (para usar nombres base.esquema.tabla).

• list_tables(schema?) — tablas y vistas.

• describe_table(table_name, schema?) — columnas, tipos, nullable, default y PK.

Notas de T-SQL

SELECT TOP 20 col1, col2 FROM dbo.tabla ORDER BY col1;
SELECT col1 FROM dbo.tabla ORDER BY col1 OFFSET 40 ROWS FETCH NEXT 20 ROWS ONLY; -- 2012+

Limitaciones conocidas

• Solo se devuelve el primer result set de una consulta.

• No se probó contra una instancia real de SQL Server en el desarrollo inicial (no había una disponible): el guard está cubierto por tests, y el arranque del servidor MCP, la construcción del connection string y el manejo de errores de conexión se verificaron, pero conviene correr scripts/test_connection.py contra tu servidor como primer paso.