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:

1. Descubra tablas en su base de datos de SQL Server

2. Ver estructuras de tablas (columnas, tipos de datos, etc.)

3. Ejecute consultas SQL de solo lectura de forma segura

4. 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

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

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

Paso 4: Iniciar el servidor

Paso 5: ¡Pruébalo!

📊 Ejemplos de casos de uso

1. Explora la estructura de tu base de datos sin escribir SQL

   mcp_SQL_mcp_discover_database()

2. Obtenga información detallada sobre una tabla específica

   mcp_SQL_mcp_table_details({ tableName: "Customers" })

3. Ejecutar una consulta segura

   mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Customers", returnResults: true })

4. Buscar tablas por patrón de nombre

   mcp_SQL_mcp_discover_tables({ namePattern: "%user%" })

5. 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 })

6. 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 })

7. 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:

1. Lista de recursos disponibles : vea qué información está disponible

2. Lista de herramientas disponibles : vea qué acciones puede realizar

3. Ejecutar consulta SQL : ejecuta una consulta SQL de solo lectura

4. Obtener detalles de la tabla : ver la estructura de cualquier tabla

5. Leer el esquema de la base de datos : ver todas las tablas y sus relaciones

6. 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:

Comandos y sintaxis esenciales

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

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:

Primero la estructura, luego la consulta

Pedir explicaciones

Notas del dialecto de SQL Server

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

Corrección del uso de herramientas

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

Solución de problemas mediante indicaciones

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

1. Sea más específico acerca de las tablas: "Antes de escribir esa consulta, verifique si la tabla CustomerOrders existe y qué columnas tiene".

2. Divida las tareas complejas en pasos: "Abordemos esto paso a paso. Primero, observe la estructura de la tabla Productos. Luego, revise la tabla Pedidos..."

3. 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".

4. 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:

1. 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" })

2. 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" })

3. 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:

Consultas analíticas

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

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:

1. Instalar Claude Desktop desde anthropic.com

2. Editar el archivo de configuración de Claude:

   • Ubicación: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Añade esta configuración:

3. Reemplace /FULL/PATH/TO/ con la ruta real a donde clonó este repositorio

4. Reiniciar Claude Desktop

5. 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

1. Abra Cursor IDE (descárguelo desde cursor.sh si no lo tiene)

2. Inicie el servidor MS SQL MCP mediante el transporte HTTP/SSE:

   npm run start:sse

3. Cree un nuevo espacio de trabajo o abra un proyecto existente en Cursor

4. Ingresar a la configuración del cursor

5. Haga clic en MCP

6. Agregar nuevo servidor MCP

7. Nombre su servidor MCP, seleccione el tipo: sse

8. 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:

1. Pídele a Claude en Cursor que explore tu base de datos:

   Can you show me the tables in my database?

2. Ejecutar consultas específicas:

   Query the top 10 records from the Customers table

3. 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

Opción 2: Transporte HTTP/SSE

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

🛡️ 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

1. Cuando se recibe una llamada de herramienta, el servidor MCP la enruta al controlador apropiado en tools.mjs

2. El controlador de herramientas valida los parámetros y construye una consulta de base de datos

3. La consulta se ejecuta a través de funciones en database.mjs , con posible paginación desde pagination.mjs

4. Los resultados se formatean y se devuelven al cliente.

5. Cualquier error se detecta y procesa mediante errors.mjs

6. 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:

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

Base de datos SQL de Azure

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