Microsoft SQL Server MCP

Un servidor MCP impulsado por .NET para interactuar con bases de datos de Microsoft SQL Server.

GitHub
155
Prueba este MCPPatrocinado

Documentación

mssql-mcp

Un servidor de Protocolo de Contexto de Modelo (MCP) impulsado por .NET para Microsoft SQL Server.

Resumen

¿Por qué existe esto? Porque las otras soluciones MCP en el mercado para esto son generalmente piezas de mala calidad que no funcionan, ciertamente no en Windows.

Este servidor MCP proporciona a los agentes de IA un acceso robusto y confiable a las bases de datos de Microsoft SQL Server a través de una aplicación .NET limpia y bien arquitecturada que utiliza Akka.NET para la coordinación interna y el SDK oficial de MCP C# para el cumplimiento del protocolo.

Características

  • Descubrimiento de Esquemas: Los agentes de IA pueden explorar la estructura de la base de datos sin escribir SQL complejo
  • Ejecución de Consultas: Soporte completo de SQL para operaciones SELECT, INSERT, UPDATE, DELETE y DDL
  • Validación de Conexión: Validación automática de conectividad de la base de datos al inicio
  • Manejo de Errores: Manejo integral de errores con mensajes de error claros y accionables
  • Formato de Tablas: Resultados de consultas formateados en tablas legibles para el consumo de IA
  • Soporte Docker: Implementación fácil con las herramientas Docker integradas de .NET

Herramientas Disponibles

HerramientaDescripción
execute_sqlEjecutar cualquier consulta SQL contra la base de datos
list_tablesListar todas las tablas con esquema, nombre, tipo y recuento de filas
list_schemasListar todos los esquemas/bases de datos disponibles en la instancia de SQL Server

Configuración

Variables de Entorno Requeridas

El servidor MCP requiere una única variable de entorno:

  • MSSQL_CONNECTION_STRING: Cadena de conexión completa de SQL Server

Ejemplos de Cadenas de Conexión

Autenticación de Windows:

MSSQL_CONNECTION_STRING="Server=localhost;Database=MyDatabase;Trusted_Connection=true;"

Autenticación de SQL Server:

MSSQL_CONNECTION_STRING="Server=localhost;Database=MyDatabase;User Id=myuser;Password=mypassword;"

Azure SQL Database:

MSSQL_CONNECTION_STRING="Server=myserver.database.windows.net;Database=mydatabase;User Id=myuser;Password=mypassword;Encrypt=true;"

Ejecución del Servidor MCP

Opción 1: Docker (Recomendado)

La forma más fácil de ejecutar el servidor MCP es usando Docker con el soporte de contenedores integrado de .NET.

Construir y Ejecutar con Docker

Clonar el repositorio

Clonar el repositorio

git clone https://github.com/Aaronontheweb/mssql-mcp.git cd mssql-mcp

Construir la imagen Docker

dotnet publish --os linux --arch x64 /t:PublishContainer

Puedes ejecutar el contenedor directamente si lo deseas, pero probablemente sea mejor dejar que el servidor MCP inicie el cliente:

Ejecutar el contenedor

docker run -it --rm
-e MSSQL_CONNECTION_STRING="Server=host.docker.internal;Database=MyDB;Trusted_Connection=true;"
mssql-mcp:latest

Configuración del Cliente MCP

IDE Cursor

Agregar a tu configuración de Cursor (Cursor Settings > Features > Model Context Protocol):

{ "mcpServers": { "mssql": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "MSSQL_CONNECTION_STRING", "mssql-mcp:latest" ], "env": { "MSSQL_CONNECTION_STRING": "Server=host.docker.internal,1533; Database=MyDb; User Id=myUser; Password=My(!)Password;TrustServerCertificate=true;" } } } }

Claude Desktop

Agregar a tu archivo de configuración de Claude Desktop:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Es posible que necesites crear ese archivo y reiniciar Claude Desktop para que los cambios surtan efecto.

Comprendiendo tu Configuración de Servidor MCP de Claude Desktop

Esta configuración JSON es para los servidores de Protocolo de Contexto de Modelo (MCP) de Claude Desktop. Esencialmente le enseña a Claude cómo conectarse y usar una "herramienta" personalizada que interactúa con una base de datos de Microsoft SQL Server (MSSQL).

Desglosemos cada parte:

mcpServers

Esta es la sección de nivel superior donde defines todos tus servidores MCP personalizados. Puedes configurar múltiples servidores aquí, cada uno con su propio nombre único.

"mssql"

Este es el nombre único que has elegido para esta integración particular de SQL Server. Claude usará este nombre para referirse a esta conexión de base de datos.

"command": "docker"

Esta línea le dice a Claude Desktop que inicie el servidor MCP usando Docker. Esto significa que el software del servidor real se ejecuta dentro de un contenedor aislado, y necesitarás Docker Desktop instalado y ejecutándose en tu máquina Windows/mac/Linux para que esto funcione. Alternativamente, puedes usar un servidor Docker remoto usando contexto personalizado.

"args": [...]

Estos son los argumentos que Claude Desktop pasa al comando docker al iniciar el contenedor:

  • "run": Este comando estándar de Docker crea e inicia un nuevo contenedor.
  • "-i": Significa "interactivo", manteniendo la entrada estándar abierta para la comunicación entre el servidor MCP y Claude Desktop.
  • "--rm": Este argumento importante le dice a Docker que elimine automáticamente el contenedor cuando se detenga. Esto ayuda a mantener tu entorno Docker ordenado.
  • "-e", "MSSQL_CONNECTION_STRING": Esto pasa una variable de entorno llamada MSSQL_CONNECTION_STRING al contenedor Docker.
  • "mssql-mcp:latest": Esto especifica la imagen Docker a usar. Esta imagen (mssql-mcp con la etiqueta latest) contiene la aplicación del servidor MCP real diseñada para interactuar con SQL Server. Necesitarás asegurarte de que esta imagen esté disponible (ya sea construida localmente o extraída de un registro Docker).
"env": {...}

Esta sección define las variables de entorno que se establecerán cuando Docker ejecute el comando.

  • "MSSQL_CONNECTION_STRING": "Server=host.docker.internal,1533; Database=MyDb; User Id=myUser; Password=My(!)Password;TrustServerCertificate=true;"
    • Esta es la cadena de conexión de SQL Server que el contenedor Docker mssql-mcp usará para conectarse a tu base de datos.
    • Server=host.docker.internal,1533: host.docker.internal es un nombre DNS especial de Docker que permite al contenedor alcanzar la dirección IP de tu máquina host. Así es como el servidor MCP dentro de Docker puede conectarse a tu instancia de SQL Server, que presumiblemente se ejecuta directamente en tu máquina. 1533 es el puerto en el que tu SQL Server está escuchando.
    • Database=MyDb: El nombre de la base de datos específica a la que deseas conectarte.
    • User Id=myUser; Password=My(!)Password;: Las credenciales para un usuario (myUser) para iniciar sesión en tu SQL Server.
    • TrustServerCertificate=true;: Esto le dice al cliente que omita la validación del certificado SSL/TLS del servidor. Aunque es conveniente para desarrollo o cuando se usan certificados autofirmados, ten en cuenta que esto reduce la seguridad al hacerte vulnerable a ataques de intermediario en entornos de producción.
En Resumen:

Esta configuración permite a Claude Desktop ejecutar un servidor MCP específico de SQL Server dentro de un contenedor Docker. Este servidor luego usa la cadena de conexión proporcionada para establecer una conexión con tu base de datos de SQL Server, permitiendo a Claude interactuar con tus datos a través de esta herramienta personalizada.

Configuración de Binario Local

Si ejecutas el binario compilado directamente en lugar de Docker:

{ "mcpServers": { "mssql": { "command": "/path/to/mssql-mcp/src/MSSQL.MCP/bin/Release/net9.0/MSSQL.MCP", "env": { "MSSQL_CONNECTION_STRING": "Server=localhost;Database=MyDB;Trusted_Connection=true;" } } } }

Problemas de Red Docker

Comprendiendo el Problema

Al ejecutar el servidor MCP como un contenedor Docker, encontrarás desafíos de red al intentar conectarte a instancias de SQL Server que se ejecutan en tu máquina host o en otros contenedores. Los contenedores Docker están aislados de la red del host por defecto, lo que hace imposibles las conexiones localhost.

Soluciones por Escenario

Escenario 1: SQL Server Ejecutándose en la Máquina Host

Problema: Tu SQL Server está instalado directamente en Windows/macOS/Linux, y deseas que el servidor MCP contenerizado se conecte a él.

Solución: Usa host.docker.internal en lugar de localhost en tu cadena de conexión.

❌ Esto no funcionará - localhost se refiere al contenedor mismo

docker run -it --rm
-e MSSQL_CONNECTION_STRING="Server=localhost;Database=MyDB;User Id=sa;Password=YourPassword123!;"
mssql-mcp:latest

✅ Esto funciona - host.docker.internal se refiere a la máquina host

docker run -it --rm
-e MSSQL_CONNECTION_STRING="Server=host.docker.internal;Database=MyDB;User Id=sa;Password=YourPassword123!;"
mssql-mcp:latest

Configuración Actualizada del Cliente MCP:

{ "mcpServers": { "mssql": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "MSSQL_CONNECTION_STRING=Server=host.docker.internal;Database=MyDB;User Id=sa;Password=YourPassword123!;", "mssql-mcp:latest" ] } } }

Escenario 2: SQL Server en Otro Contenedor Docker

Solución: Usa Docker Compose con una red personalizada y referencia los contenedores por nombre de servicio.

version: '3.8' networks: sql-network: driver: bridge

services: mssql-mcp: build: . environment: # Usa el nombre del servicio 'sqlserver' como nombre de host - MSSQL_CONNECTION_STRING=Server=sqlserver;Database=MyDatabase;User Id=sa;Password=YourPassword123!; stdin_open: true tty: true networks: - sql-network depends_on: - sqlserver

sqlserver: image: mcr.microsoft.com/mssql/server:2022-latest environment: - ACCEPT_EULA=Y - SA_PASSWORD=YourPassword123! networks: - sql-network ports: - "1433:1433" # Exponer al host para herramientas externas

Escenario 3: Linux con Modo de Red del Host

Solución Solo para Linux: Usa el modo de red del host de Docker para acceso directo a la red del host.

Solo Linux - comparte la pila de red del host

docker run -it --rm --network host
-e MSSQL_CONNECTION_STRING="Server=localhost;Database=MyDB;User Id=sa;Password=YourPassword123!;"
mssql-mcp:latest

Consideraciones Específicas por Plataforma

Plataformahost.docker.internalModo de Red del HostSolución Recomendada
Windows✅ Funciona de fábrica❌ No soportadoUsar host.docker.internal
macOS✅ Funciona de fábrica❌ No soportadoUsar host.docker.internal
Linux⚠️ Requiere --add-host✅ SoportadoUsar --network host o host.docker.internal

Configuración de host.docker.internal en Linux:

docker run -it --rm
--add-host=host.docker.internal:host-gateway
-e MSSQL_CONNECTION_STRING="Server=host.docker.internal;Database=MyDB;User Id=sa;Password=YourPassword123!;"
mssql-mcp:latest

Prueba de Conectividad de Red

Para verificar que tu contenedor puede alcanzar el SQL Server:

Prueba desde dentro de un contenedor en ejecución

docker exec -it <container_name> ping host.docker.internal

Prueba el puerto de SQL Server específicamente

docker run --rm -it mcr.microsoft.com/mssql-tools
/bin/bash -c "sqlcmd -S host.docker.internal -U sa -P 'YourPassword123!' -Q 'SELECT @@VERSION'"

Solución de Problemas Comunes de Red

  1. Conexión Rechazada:
    • Verifica que SQL Server esté escuchando en todas las interfaces: netstat -an | grep 1433
    • Comprueba que el Firewall de Windows permita el acceso a la subred de Docker
  2. Resolución DNS:
    • Prueba: docker run --rm busybox nslookup host.docker.internal
    • Asegúrate de que Docker Desktop esté ejecutándose (para Windows/macOS)
  3. Contenedor a Contenedor:
    • Verifica que ambos contenedores estén en la misma red Docker
    • Usa nombres de servicio de contenedores, no localhost
  4. Conflictos de Puertos:
    • Asegúrate de que el puerto 1433 no esté ya vinculado por otro proceso
    • Verifica con: netstat -tlnp | grep 1433

Ejemplos de Uso

Una vez configurado, los agentes de IA pueden usar lenguaje natural para interactuar con tu base de datos:

"Muéstrame todas las tablas en la base de datos"→ Usa la herramienta list_tables

"Describe la estructura de la tabla Usuarios"→ Usa execute_sql con una consulta INFORMATION_SCHEMA

"Encuentra todos los usuarios creados en los últimos 30 días"→ Usa execute_sql con la consulta SELECT apropiada

"Crea un nuevo registro de cliente"→ Usa execute_sql con una declaración INSERT

Consideraciones de Seguridad

⚠️ Advertencias de Seguridad Importantes

  • Permisos de base de datos: Otorgue únicamente los permisos mínimos requeridos al usuario de la base de datos
  • Seguridad de conexión: Utilice conexiones cifradas para entornos de producción
  • Control de acceso: Este servidor MCP proporciona capacidades completas de ejecución de SQL; asegúrese de contar con controles de acceso adecuados
  • Registro de auditoría: Considere habilitar el registro de auditoría de SQL Server para uso en producción
  • Seguridad de red: Restrinja adecuadamente el acceso de red al servidor de base de datos

Permisos de base de datos recomendados

Para acceso de solo lectura:

-- Crear un usuario dedicado con permisos mínimos CREATE LOGIN mcp_readonly WITH PASSWORD = 'SecurePassword123!'; CREATE USER mcp_readonly FOR LOGIN mcp_readonly;

-- Otorgar solo los permisos necesarios GRANT SELECT ON SCHEMA::dbo TO mcp_readonly; GRANT VIEW DEFINITION ON SCHEMA::dbo TO mcp_readonly;

Para acceso de lectura y escritura:

-- Crear un usuario dedicado CREATE LOGIN mcp_readwrite WITH PASSWORD = 'SecurePassword123!'; CREATE USER mcp_readwrite FOR LOGIN mcp_readwrite;

-- Otorgar los permisos necesarios GRANT SELECT, INSERT, UPDATE, DELETE ON SCHEMA::dbo TO mcp_readwrite; GRANT VIEW DEFINITION ON SCHEMA::dbo TO mcp_readwrite;

Solución de problemas

Problemas de conexión

  1. Verifique la cadena de conexión: Pruebe con SQL Server Management Studio o Azure Data Studio
  2. Revise el firewall: Asegúrese de que el puerto de SQL Server (1433 por defecto) sea accesible
  3. Habilite TCP/IP: Asegúrese de que el protocolo TCP/IP esté habilitado en el Administrador de configuración de SQL Server
  4. Modo de autenticación: Verifique que SQL Server esté configurado para el modo de autenticación adecuado

Problemas con contenedores

  1. Conectividad de red: Utilice host.docker.internal en lugar de localhost al conectarse desde el contenedor al host
  2. Variables de entorno: Asegúrese de que la cadena de conexión esté correctamente escapada en los comandos de Docker
  3. Registros: Revise los registros del contenedor con docker logs <container_id>

Licencia

Este software está licenciado bajo Apache 2.0 y está disponible "tal cual"; esto significa que si usted destruye su base de datos porque le dio a un agente de IA acceso sa a través de este servidor MCP, no somos responsables.

Contribuciones

  1. Haga un fork del repositorio
  2. Cree una rama de características
  3. Realice sus cambios
  4. Agregue pruebas si corresponde
  5. Envíe una solicitud de extracción (pull request)

Arquitectura

  • Akka.NET: Se utiliza para la coordinación interna del sistema de actores y la validación de la base de datos
  • MCP C# SDK: Implementación oficial del Protocolo de Contexto de Modelo
  • Microsoft.Data.SqlClient: Conectividad de alto rendimiento con SQL Server