MCP SQL Server

Un servidor de Model Context Protocol (MCP) de solo lectura para Microsoft SQL Server que permite a los agentes de IA explorar y consultar bases de datos SQL Server de forma segura.

Inicio rápido

Paso 1: Instalar el paquete

# Global installation (recommended)
npm install -g @bilims/mcp-sqlserver

# Verify installation
mcp-sqlserver --version

Paso 2: Configurar tu conexión a SQL Server

Elige tu tipo de SQL Server y sigue la configuración:

Azure SQL Database

export SQLSERVER_HOST="your-server.database.windows.net"
export SQLSERVER_USER="your-username"
export SQLSERVER_PASSWORD="your-password"
export SQLSERVER_DATABASE="your-database"
export SQLSERVER_ENCRYPT="true"
export SQLSERVER_TRUST_CERT="false"

SQL Server local

export SQLSERVER_HOST="your-sql-server.company.com"
export SQLSERVER_USER="your-username"
export SQLSERVER_PASSWORD="your-password"
export SQLSERVER_DATABASE="your-database"
export SQLSERVER_ENCRYPT="true"
export SQLSERVER_TRUST_CERT="true"  # For self-signed certificates

SQL Server Express local

export SQLSERVER_HOST="localhost\\SQLEXPRESS"
export SQLSERVER_USER="sa"
export SQLSERVER_PASSWORD="your-password"
export SQLSERVER_DATABASE="master"
export SQLSERVER_ENCRYPT="false"
export SQLSERVER_TRUST_CERT="true"

Paso 3: Probar la conexión

# Test your configuration
mcp-sqlserver --help

# Quick connection test (press Ctrl+C to exit)
mcp-sqlserver

Paso 4: Añadir a Claude Desktop

1. Encuentra tu archivo de configuración de Claude Desktop:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Añade la configuración del servidor MCP:

{
  "mcpServers": {
    "sqlserver": {
      "command": "mcp-sqlserver",
      "env": {
        "SQLSERVER_HOST": "your-server.database.windows.net",
        "SQLSERVER_USER": "your-username",
        "SQLSERVER_PASSWORD": "your-password",
        "SQLSERVER_DATABASE": "your-database",
        "SQLSERVER_ENCRYPT": "true",
        "SQLSERVER_TRUST_CERT": "false"
      }
    }
  }
}

3. Reinicia Claude Desktop

Paso 5: ¡Empieza a explorar!

Prueba estos comandos en Claude Desktop:

• "Probar la conexión a SQL Server"

• "Listar todas las bases de datos del servidor"

• "Mostrar las tablas en [nombre de la base de datos]"

• "Describir la estructura de la tabla Users"

• "Mostrar las relaciones de clave externa"

Related MCP server: SQL Server MCP

Características

• 🔒 Operaciones de solo lectura: Solo se permiten consultas SELECT, con validación de seguridad integral

• 🗄️ Descubrimiento de esquemas: Explora bases de datos, tablas, vistas, relaciones y metadatos

• 📊 Exploración de datos: Ejecuta consultas seguras con límites y tiempos de espera integrados

• 🔐 Listo para empresas: Conexiones cifradas con confianza de certificados para entornos de producción

• 🛡️ Seguridad primero: Validación de consultas, protección contra inyección SQL y controles de acceso

Herramientas disponibles

Descubrimiento de esquemas

• list_databases - Lista todas las bases de datos en la instancia de SQL Server

• list_tables - Lista las tablas en una base de datos o esquema

• list_views - Lista las vistas en una base de datos o esquema

• describe_table - Obtiene el esquema detallado de una tabla, incluyendo columnas, tipos de datos y restricciones

Análisis de relaciones

• get_foreign_keys - Obtiene las relaciones de clave externa de las tablas

• get_table_stats - Obtiene estadísticas de tablas, incluyendo recuentos de filas e información de tamaño

Exploración de datos

• execute_query - Ejecuta consultas SELECT de solo lectura con validación de seguridad

• get_server_info - Obtiene la versión, edición y detalles de configuración de SQL Server

Comandos comunes para Claude Desktop

Una vez que tu servidor MCP esté configurado, prueba estos comandos en lenguaje natural:

Comandos de inicio

"Test the SQL Server connection"
"Show me server information"
"List all databases on this server"
"What tables are in the [database name] database?"

Exploración de bases de datos

"Describe the structure of the Users table"
"Show me foreign key relationships in this database"
"What are the largest tables by row count?"
"Give me a sample of data from the Orders table"

Análisis avanzado

"Help me understand the relationship between Orders and Customers"
"Show me all lookup tables in this database"
"What columns contain date/time information?"
"Find tables that might contain user authentication data"

Consultas personalizadas

"Run this query: SELECT TOP 10 * FROM Products WHERE Price > 100"
"Show me all customers created in the last 30 days"
"What are the different product categories in the database?"

Instalación

npm install
npm run build

Configuración

El servidor se configura mediante variables de entorno:

Requeridas

• SQLSERVER_USER - Nombre de usuario de SQL Server

• SQLSERVER_PASSWORD - Contraseña de SQL Server

Opcionales

• SQLSERVER_HOST - Hostname del servidor (por defecto: localhost)

• SQLSERVER_DATABASE - Nombre de la base de datos por defecto

• SQLSERVER_PORT - Número de puerto (por defecto: 1433)

• SQLSERVER_ENCRYPT - Habilitar cifrado (por defecto: true)

• SQLSERVER_TRUST_CERT - Confiar en el certificado del servidor (por defecto: true)

• SQLSERVER_CONNECTION_TIMEOUT - Tiempo de espera de conexión en ms (por defecto: 30000)

• SQLSERVER_REQUEST_TIMEOUT - Tiempo de espera de solicitud en ms (por defecto: 60000)

• SQLSERVER_MAX_ROWS - Máximo de filas por consulta (por defecto: 1000)

Uso

Variables de entorno

export SQLSERVER_HOST="your-server.database.windows.net"
export SQLSERVER_USER="your-username"
export SQLSERVER_PASSWORD="your-password"
export SQLSERVER_DATABASE="your-database"
export SQLSERVER_ENCRYPT="true"
export SQLSERVER_TRUST_CERT="true"

Ejecutar el servidor

npm start

Opciones de instalación

Opción 1: Instalación global (recomendada)

npm install -g @bilims/mcp-sqlserver

Opción 2: Instalación local

npm install @bilims/mcp-sqlserver
npx mcp-sqlserver

Opción 3: Ejecutar con npx (sin instalación)

npx @bilims/mcp-sqlserver

Ejemplos de integración

Claude Desktop

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

{
  "mcpServers": {
    "sqlserver": {
      "command": "mcp-sqlserver",
      "env": {
        "SQLSERVER_HOST": "your-server.database.windows.net",
        "SQLSERVER_USER": "your-username",
        "SQLSERVER_PASSWORD": "your-password",
        "SQLSERVER_DATABASE": "your-database"
      }
    }
  }
}

Claude Code CLI

# Set environment variables
export SQLSERVER_HOST="your-server"
export SQLSERVER_USER="your-username"
export SQLSERVER_PASSWORD="your-password"

# Use with Claude Code
claude mcp add sqlserver mcp-sqlserver

VSCode con extensión MCP

Instala la extensión MCP para VSCode y añade la configuración del servidor.

Características de seguridad

Validación de consultas

• Solo se permiten sentencias SELECT, WITH, SHOW, DESCRIBE y EXPLAIN

• Lista negra integral de palabras clave peligrosas (INSERT, UPDATE, DELETE, DROP, etc.)

• Detección de patrones de inyección SQL

• Saneamiento automático de consultas

Seguridad de la conexión

• Cifrado TLS/SSL habilitado por defecto

• Opciones de confianza de certificados del servidor para entornos empresariales

• Agrupación de conexiones con controles de tiempo de espera

• Tiempos de espera de solicitud configurables

Límites de resultados

• Límites máximos de filas por consulta (configurables)

• Inyección automática de la cláusula TOP en consultas SELECT

• Seguimiento del tiempo de ejecución de consultas

• Protección del uso de memoria

Consultas de ejemplo

Una vez conectado, puedes usar las herramientas a través de tu cliente MCP:

// List all databases
await callTool("list_databases", {});

// List tables in a specific schema
await callTool("list_tables", { schema: "dbo" });

// Get table schema details
await callTool("describe_table", { 
  table_name: "Users", 
  schema: "dbo" 
});

// Execute a read-only query
await callTool("execute_query", { 
  query: "SELECT TOP 10 * FROM Users WHERE active = 1",
  limit: 10
});

// Get foreign key relationships
await callTool("get_foreign_keys", { 
  table_name: "Orders" 
});

Desarrollo

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run linting
npm run lint

# Run tests
npm test

Solución de problemas

Problemas de conexión

1. Verifica el hostname y el puerto del servidor

2. Comprueba que la configuración de cifrado/certificado coincida con tu configuración de SQL Server

3. Asegúrate de que el usuario tenga los permisos de lectura adecuados

4. Prueba primero la conexión con SQL Server Management Studio

Problemas de permisos

La cuenta de usuario necesita como mínimo:

• Permiso CONNECT en la base de datos

• Permiso SELECT en las tablas/vistas que quieras consultar

• Acceso a las vistas del sistema para consultas de metadatos

Configuraciones comunes de SQL Server

Azure SQL Database

export SQLSERVER_HOST="your-server.database.windows.net"
export SQLSERVER_ENCRYPT="true"
export SQLSERVER_TRUST_CERT="false"

SQL Server local con certificados autofirmados

export SQLSERVER_HOST="sql-server.company.com"
export SQLSERVER_ENCRYPT="true" 
export SQLSERVER_TRUST_CERT="true"

Licencia

MIT

Contribuciones

1. Haz un fork del repositorio

2. Crea una rama de características

3. Realiza tus cambios

4. Añade pruebas si corresponde

5. Envía una solicitud de extracción (pull request)

Soporte

Para problemas y preguntas:

• Consulta la sección de solución de problemas anterior

• Revisa la documentación de conexión de SQL Server

• Asegura la compatibilidad con tu cliente MCP

Construido con el Model Context Protocol SDK para una integración fluida con IA.