Servidor MS SQL MCP 1.1

Un puente fácil de usar que permite a asistentes de IA como Claude consultar y explorar directamente bases de datos de Microsoft SQL Server. ¡No se requiere experiencia en programación!

¿Qué hace esta herramienta?

Esta herramienta permite a los asistentes de IA:

Descubra tablas en su base de datos de SQL Server
Ver estructuras de tablas (columnas, tipos de datos, etc.)
Ejecute consultas SQL de solo lectura de forma segura
Generar consultas SQL a partir de solicitudes en lenguaje natural

🌟Por qué necesitas esta herramienta

Cierre la brecha entre sus datos y la IA

No se requiere codificación : brinde a Claude y otros asistentes de IA acceso directo a sus bases de datos de SQL Server sin escribir código de integración complejo
Mantener el control : todas las consultas son de solo lectura de forma predeterminada, lo que garantiza que sus datos permanezcan seguros.
Privado y seguro : las credenciales de su base de datos permanecen locales y nunca se envían a servicios externos.

Beneficios prácticos

Ahorre horas de trabajo manual : ya no es necesario copiar y pegar datos ni resultados de consultas para compartir con IA.
Análisis más profundo : la IA puede navegar por todo el esquema de su base de datos y brindar información en múltiples tablas
Interfaz de lenguaje natural : haga preguntas sobre sus datos en un inglés sencillo
Ponga fin al problema del límite de contexto : acceda a grandes conjuntos de datos que superarían las ventanas de contexto de IA normales

Perfecto para

Analistas de datos que desean que la IA ayude a interpretar datos SQL sin compartir credenciales
Desarrolladores que buscan una forma rápida de explorar la estructura de la base de datos a través de una conversación natural.
Analistas de negocios que necesitan información sin experiencia en SQL
Administradores de bases de datos que desean proporcionar acceso controlado a herramientas de IA

🚀 Guía de inicio rápido

Paso 1: Instalar requisitos previos

Instalar Node.js (versión 14 o superior)
Tener acceso a una base de datos de Microsoft SQL Server (local o Azure)

Paso 2: Clonar y configurar

# Clone this repository
git clone https://github.com/dperussina/mssql-mcp-server.git

# Navigate to the project directory
cd mssql-mcp-server

# Install dependencies
npm install

# Copy the example environment file
cp .env.example .env

Paso 3: Configure su conexión a la base de datos

Edite el archivo .env con las credenciales de su base de datos:

DB_USER=your_username
DB_PASSWORD=your_password
DB_SERVER=your_server_name_or_ip
DB_DATABASE=your_database_name
PORT=3333
TRANSPORT=stdio
SERVER_URL=http://localhost:3333
DEBUG=false                     # Set to 'true' for detailed logging (helpful for troubleshooting)
QUERY_RESULTS_PATH=/path/to/query_results  # Directory where query results will be saved as JSON files

Paso 4: Iniciar el servidor

# Start with default stdio transport
npm start

# OR start with HTTP/SSE transport for network access
npm run start:sse

Paso 5: ¡Pruébalo!

# Run the interactive client
npm run client

📊 Ejemplos de casos de uso

Explora la estructura de tu base de datos sin escribir SQL
mcp_SQL_mcp_discover_database()
Obtenga información detallada sobre una tabla específica
mcp_SQL_mcp_table_details({ tableName: "Customers" })
Ejecutar una consulta segura
mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Customers", returnResults: true })
Buscar tablas por patrón de nombre
mcp_SQL_mcp_discover_tables({ namePattern: "%user%" })
Utilice la paginación para navegar por grandes conjuntos de resultados
// First page mcp_SQL_mcp_execute_query({ sql: "SELECT * FROM Users ORDER BY Username OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY", returnResults: true }) // Next page mcp_SQL_mcp_execute_query({ sql: "SELECT * FROM Users ORDER BY Username OFFSET 10 ROWS FETCH NEXT 10 ROWS ONLY", returnResults: true })
Paginación basada en cursor para un rendimiento óptimo
// First page mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Users ORDER BY Username", returnResults: true }) // Next page using the last value as cursor mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Users WHERE Username > 'last_username' ORDER BY Username", returnResults: true })
Haga preguntas en lenguaje natural
"Show me the top 5 customers with the most orders in the last month"

💡 Aplicaciones en el mundo real

Para inteligencia empresarial

Análisis del rendimiento de ventas : "Muéstrame las tendencias de ventas mensuales del último año e identifica nuestros productos con mejor rendimiento por región".
Segmentación de clientes : "Analizar nuestra base de clientes por frecuencia de compra, valor promedio de pedido y ubicación geográfica".
Informes financieros : "Crear un informe trimestral de ganancias y pérdidas comparando este año con el año pasado".

Para la gestión de bases de datos

Optimización del esquema : "Ayúdeme a identificar tablas con índices faltantes examinando los datos de rendimiento de las consultas".
Auditoría de calidad de datos : "Encuentre todos los registros de clientes con información incompleta o valores no válidos".
Análisis de uso : "Muéstrame qué tablas son las que se acceden con más frecuencia y qué consultas consumen más recursos".

Para el desarrollo

Exploración de API : "Estoy creando una API. Ayúdenme a analizar el esquema de la base de datos para diseñar puntos finales apropiados".
Optimización de consultas : "Revise esta consulta compleja y sugiera mejoras de rendimiento".
Documentación de base de datos : "Crear documentación completa de la estructura de nuestra base de datos con explicaciones de las relaciones".

🖥️ Funciones interactivas del cliente

El cliente incluido proporciona una interfaz sencilla basada en menús:

Lista de recursos disponibles : vea qué información está disponible
Lista de herramientas disponibles : vea qué acciones puede realizar
Ejecutar consulta SQL : ejecuta una consulta SQL de solo lectura
Obtener detalles de la tabla : ver la estructura de cualquier tabla
Leer el esquema de la base de datos : ver todas las tablas y sus relaciones
Generar consulta SQL : convertir lenguaje natural a SQL

Guía eficaz para el uso de herramientas y sugerencias

Al trabajar con Claude u otros asistentes de IA a través de este servidor MCP, la forma en que formulas tus solicitudes influye significativamente en los resultados. Así es como puedes ayudar a la IA a usar las herramientas de la base de datos eficazmente:

Formato básico de llamada a herramientas

Al solicitarle a una IA que use esta herramienta, siga esta estructura:

Can you use the SQL MCP tools to [your goal]?

For example:
- Check what tables exist in my database
- Query the Customers table and show me the first 10 records
- Find all orders from the past month

Comandos y sintaxis esenciales

Aquí están las herramientas principales y su sintaxis correcta:

// Discover the database structure
mcp_SQL_mcp_discover_database()

// Get detailed information about a specific table
mcp_SQL_mcp_table_details({ tableName: "YourTableName" })

// Execute a query and return results
mcp_SQL_mcp_execute_query({ 
  sql: "SELECT * FROM YourTable WHERE Condition", 
  returnResults: true 
})

// Find tables by name pattern
mcp_SQL_mcp_discover_tables({ namePattern: "%pattern%" })

// Access saved query results (for large result sets)
mcp_SQL_mcp_get_query_results({ uuid: "provided-uuid-here" })

Cuándo utilizar cada herramienta:

Descubrimiento de base de datos : comience con esto cuando la IA no esté familiarizada con la estructura de su base de datos.
Detalles de la tabla : Úselo cuando se centre en una tabla específica antes de escribir consultas.
Ejecución de consultas : cuando necesita recuperar o analizar datos reales.
Descubrimiento de tablas por patrón : al buscar tablas relacionadas con un dominio específico.

Patrones de estímulo efectivos

Flujos de trabajo paso a paso

Para tareas complejas, guíe a la IA a través de una serie de pasos:

I'd like to analyze our sales data. Please:
First use mcp_SQL_mcp_discover_tables to find tables related to sales
Use mcp_SQL_mcp_table_details to examine the structure of relevant tables
Create a query with mcp_SQL_mcp_execute_query that shows monthly sales by product category

Primero la estructura, luego la consulta

First, discover what tables exist in my database. Then, look at the structure
of the Customers table. Finally, show me the top 10 customers by total purchase amount.

Pedir explicaciones

Query the top 5 underperforming products based on sales vs. forecasts,
and explain your approach to writing this query.

Notas del dialecto de SQL Server

Recuerde a la IA la sintaxis específica de SQL Server:

Please use SQL Server syntax for pagination:
- For offset/fetch: "OFFSET 10 ROWS FETCH NEXT 10 ROWS ONLY"
- For cursor-based: "WHERE ID > last_id ORDER BY ID"

Corrección del uso de herramientas

Si la IA utiliza una sintaxis incorrecta, puedes ayudarla con lo siguiente:

That's not quite right. Please use this format for the tool call:
mcp_SQL_mcp_execute_query({ 
  sql: "SELECT * FROM Customers WHERE Region = 'West'",
  returnResults: true
})

Solución de problemas mediante indicaciones

Si la IA tiene dificultades con una tarea de base de datos, pruebe estos enfoques:

Sea más específico acerca de las tablas: "Antes de escribir esa consulta, verifique si la tabla CustomerOrders existe y qué columnas tiene".
Divida las tareas complejas en pasos: "Abordemos esto paso a paso. Primero, observe la estructura de la tabla Productos. Luego, revise la tabla Pedidos..."
Solicitar resultados intermedios: "Ejecute primero una consulta simple en esa tabla para que podamos verificar el formato de los datos antes de intentar un análisis más complejo".
Solicitar explicaciones de la consulta: "Después de escribir esta consulta, explique qué hace cada parte para que pueda verificar que hace lo que necesito".

🔎 Capacidades de consulta avanzadas

Descubrimiento y exploración de mesas

El servidor MCP proporciona herramientas potentes para explorar la estructura de su base de datos:

Descubrimiento de tablas basado en patrones : encuentre tablas que coincidan con patrones específicos
mcp_SQL_mcp_discover_tables({ namePattern: "%order%" })
Descripción general del esquema : obtenga una vista de alto nivel de las tablas por esquema
mcp_SQL_mcp_execute_query({ sql: "SELECT TABLE_SCHEMA, COUNT(*) AS TableCount FROM INFORMATION_SCHEMA.TABLES GROUP BY TABLE_SCHEMA" })
Exploración de columnas : Examine los metadatos de las columnas de cualquier tabla
mcp_SQL_mcp_table_details({ tableName: "dbo.Users" })

Técnicas de paginación

El servidor admite múltiples métodos de paginación para gestionar grandes conjuntos de datos:

Paginación de desplazamiento/obtención : paginación SQL estándar mediante OFFSET y FETCH
mcp_SQL_mcp_execute_query({ sql: "SELECT * FROM Users ORDER BY Username OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY" })
Paginación basada en cursor : más eficiente para grandes conjuntos de datos
// Get first page mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Users ORDER BY Username" }) // Get next page using last value as cursor mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Users WHERE Username > 'last_username' ORDER BY Username" })
Contar con datos : recuperar el recuento total junto con los datos paginados
mcp_SQL_mcp_execute_query({ sql: "WITH TotalCount AS (SELECT COUNT(*) AS Total FROM Users) SELECT TOP 10 u.*, t.Total FROM Users u CROSS JOIN TotalCount t ORDER BY Username" })

Uniones y relaciones complejas

Explora las relaciones entre tablas con operaciones de unión:

mcp_SQL_mcp_execute_query({ 
  sql: "SELECT u.Username, u.Email, r.RoleName FROM Users u JOIN UserRoles ur ON u.Username = ur.Username JOIN Roles r ON ur.RoleId = r.RoleId ORDER BY u.Username"
})

Consultas analíticas

Ejecute agregaciones y consultas analíticas para obtener información:

mcp_SQL_mcp_execute_query({ 
  sql: "SELECT UserType, COUNT(*) AS UserCount, SUM(CASE WHEN IsActive = 1 THEN 1 ELSE 0 END) AS ActiveUsers FROM Users GROUP BY UserType"
})

Uso de las características de SQL Server

El servidor MCP admite características específicas de SQL Server:

Expresiones de tabla comunes (CTE)
Funciones de ventana
Operaciones JSON
Consultas jerárquicas
Búsqueda de texto completo (cuando esté configurada en su base de datos)

🔗 Opciones de integración

Integración de escritorio de Claude

Conecte esta herramienta directamente a Claude Desktop en unos sencillos pasos:

Instalar Claude Desktop desde anthropic.com
Editar el archivo de configuración de Claude:
- Ubicación: ~/Library/Application Support/Claude/claude_desktop_config.json
- Añade esta configuración:

{
    "mcpServers": {
        "mssql": {
            "command": "node",
            "args": [
                "/FULL/PATH/TO/mssql-mcp-server/server.mjs"
            ]
        }
    }
}

Reemplace /FULL/PATH/TO/ con la ruta real a donde clonó este repositorio
Reiniciar Claude Desktop
Busque el ícono de herramientas en Claude Desktop: ¡ahora puede usar comandos de base de datos directamente!

Conexión con Cursor IDE

Cursor es un editor de código basado en IA que permite usar esta herramienta para interacciones avanzadas con bases de datos. Aquí te explicamos cómo configurarlo:

Configuración en el cursor

Abra Cursor IDE (descárguelo desde cursor.sh si no lo tiene)
Inicie el servidor MS SQL MCP mediante el transporte HTTP/SSE:
npm run start:sse
Cree un nuevo espacio de trabajo o abra un proyecto existente en Cursor
Ingresar a la configuración del cursor
Haga clic en MCP
Agregar nuevo servidor MCP
Nombre su servidor MCP, seleccione el tipo: sse
Ingrese la URL del servidor como: localhost:3333/sse (o el puerto en el que lo tiene ejecutándose)

Uso de comandos de base de datos en el cursor

Una vez conectado, puedes usar los comandos MCP directamente en el chat de IA de Cursor:

Pídele a Claude en Cursor que explore tu base de datos:
Can you show me the tables in my database?
Ejecutar consultas específicas:
Query the top 10 records from the Customers table
Generar y ejecutar consultas complejas:
Find all orders from the last month with a value over $1000

Solución de problemas de conexión del cursor

Asegúrese de que el servidor MS SQL MCP se esté ejecutando con el transporte HTTP/SSE
Verifique que el puerto sea correcto y coincida con el que figura en su archivo .env
Asegúrese de que su firewall no esté bloqueando la conexión
Si usa una IP/nombre de host diferente, actualice SERVER_URL en su archivo .env

Métodos de transporte explicados

Opción 1: Transporte stdio (predeterminado)

Ideal para: usar directamente con Claude Desktop o el cliente incluido

npm start

Opción 2: Transporte HTTP/SSE

Ideal para: acceso a la red o cuando se utiliza con aplicaciones web

npm run start:sse

🛡️ Funciones de seguridad

Solo lectura por defecto : sin riesgo de modificación de datos
Credenciales privadas : Los detalles de conexión a la base de datos permanecen en su archivo .env
Protección contra inyección SQL : validación integrada para consultas SQL

🔎 Solución de problemas para nuevos usuarios

"No se puede conectar a la base de datos"

Verifique su archivo .env para verificar las credenciales de base de datos correctas
Asegúrese de que su SQL Server esté ejecutándose y aceptando conexiones
Para Azure SQL, verifique que su IP esté permitida en la configuración del firewall

Errores de "Módulo no encontrado"

Ejecute npm install nuevamente para asegurarse de que todas las dependencias estén instaladas
Asegúrate de estar utilizando Node.js versión 14 o superior

"Error de transporte" o "Conexión rechazada"

Para el transporte HTTP/SSE, verifique que el PUERTO en su .env esté disponible
Asegúrese de que ningún firewall esté bloqueando la conexión

Claude Desktop no se puede conectar

Verifique nuevamente la ruta en su claude_desktop_config.json
Asegúrese de utilizar rutas absolutas, no relativas
Reinicie Claude Desktop por completo después de realizar cambios

📚 Comprensión de los conceptos básicos de SQL Server

Si eres nuevo en SQL Server, aquí hay algunos conceptos clave:

Tablas : almacene sus datos en filas y columnas
Esquemas : agrupaciones lógicas de tablas (como carpetas)
Consultas : Comandos para recuperar o analizar datos
Vistas : Consultas predefinidas guardadas para facilitar el acceso

¡Esta herramienta te ayuda a explorar todo esto sin necesidad de ser un experto en SQL!

🏗️ Arquitectura y módulos principales

El servidor MS SQL MCP está construido con una arquitectura modular que separa las preocupaciones por la capacidad de mantenimiento y la extensibilidad:

Módulos principales

`database.mjs` - Conectividad de bases de datos

Administra la agrupación de conexiones de SQL Server
Proporciona ejecución de consultas con lógica de reintento y manejo de errores.
Maneja conexiones de bases de datos, transacciones y configuración.
Incluye utilidades para desinfectar errores de formato y SQL.

`tools.mjs` - Registro de herramientas

Registra todas las herramientas de base de datos con el servidor MCP
Implementa la validación de herramientas y la verificación de parámetros.
Proporciona funcionalidad básica para consultas SQL, exploración de tablas y descubrimiento de bases de datos.
Llamadas de la herramienta Mapas a operaciones de base de datos

`resources.mjs` - Recursos de base de datos

Expone metadatos de la base de datos a través de puntos finales de recursos
Proporciona información de esquema, listados de tablas y documentación de procedimientos.
Formatea la información de la estructura de la base de datos para el consumo de IA
Incluye utilidades de descubrimiento para la exploración de bases de datos.

`pagination.mjs` - Navegación de resultados

Implementa paginación basada en cursor para conjuntos de resultados grandes
Proporciona utilidades para generar cursores de página siguiente/anterior
Transforma las consultas SQL para admitir la paginación
Maneja la sintaxis de paginación OFFSET/FETCH de SQL Server

`errors.mjs` - Manejo de errores

Define tipos de errores personalizados para diferentes escenarios de falla.
Implementa el formato de error JSON-RPC
Proporciona mensajes de error legibles por humanos
Incluye middleware para el manejo global de errores

`logger.mjs` - Sistema de registro

Configura el registro de Winston con múltiples transportes
Proporciona registro de solicitudes según el contexto
Maneja la rotación y el formato del registro
Captura excepciones no detectadas y rechazos no controlados

Cómo funcionan juntos estos módulos

Cuando se recibe una llamada de herramienta, el servidor MCP la enruta al controlador apropiado en tools.mjs
El controlador de herramientas valida los parámetros y construye una consulta de base de datos
La consulta se ejecuta a través de funciones en database.mjs , con posible paginación desde pagination.mjs
Los resultados se formatean y se devuelven al cliente.
Cualquier error se detecta y procesa mediante errors.mjs
Todas las operaciones se registran mediante logger.mjs

Esta arquitectura garantiza:

Separación clara de preocupaciones
Manejo consistente de errores
Registro completo
Gestión eficiente de la conexión a bases de datos
Ejecución de consultas escalable

⚙️ Explicación de la configuración del entorno

El archivo .env controla cómo se conecta y opera el servidor MS SQL MCP a su base de datos. A continuación, se detalla cada configuración:

# Database Connection Settings
DB_USER=your_username           # SQL Server username
DB_PASSWORD=your_password       # SQL Server password
DB_SERVER=your_server_name      # Server hostname or IP address (example: localhost, 10.0.0.1, myserver.database.windows.net)
DB_DATABASE=your_database_name  # Name of the database to connect to

# Server Configuration
PORT=3333                       # Port for the HTTP/SSE server to listen on
TRANSPORT=stdio                 # Connection method: 'stdio' (for Claude Desktop) or 'sse' (for network connections)
SERVER_URL=http://localhost:3333 # Base URL when using SSE transport (must match your PORT setting)

# Advanced Settings
DEBUG=false                     # Set to 'true' for detailed logging (helpful for troubleshooting)
QUERY_RESULTS_PATH=/path/to/query_results  # Directory where query results will be saved as JSON files

Explicación de los tipos de conexión

Transporte de stdio

Úselo al conectarse directamente con Claude Desktop
La comunicación se realiza a través de flujos de entrada/salida estándar.
Establezca TRANSPORT=stdio en su archivo .env
Ejecutar con npm start

Transporte HTTP/SSE

Úselo cuando se conecta a través de una red (como con Cursor IDE)
Utiliza eventos enviados por el servidor (SSE) para la comunicación en tiempo real
Establezca TRANSPORT=sse en su archivo .env
Configure SERVER_URL para que coincida con la dirección de su servidor
Ejecutar con npm run start:sse

Ejemplos de conexión a SQL Server

Servidor SQL local

DB_USER=sa
DB_PASSWORD=YourStrongPassword
DB_SERVER=localhost
DB_DATABASE=AdventureWorks

Base de datos SQL de Azure

DB_USER=azure_admin@myserver
DB_PASSWORD=YourStrongPassword
DB_SERVER=myserver.database.windows.net
DB_DATABASE=AdventureWorks

Almacenamiento de resultados de consultas

Los resultados de la consulta se guardan como archivos JSON en el directorio especificado por QUERY_RESULTS_PATH . Esto evita que grandes conjuntos de resultados saturen la conversación. Puedes:

Deje este campo en blanco para utilizar el directorio query-results predeterminado en el proyecto.
Establezca una ruta personalizada como /Users/username/Documents/query-results
Acceda a los resultados guardados utilizando el UUID proporcionado en la respuesta de la herramienta

📝 Licencia

ISC