ChatQL MCP Server

Consulta bases de datos de SQL Server usando lenguaje natural con modelos OpenAI GPT.

Documentación

ChatQL MCP Server

Un potente servidor Model Context Protocol (MCP) que permite consultas en lenguaje natural a bases de datos SQL Server. Transforma tus preguntas en inglés en consultas SQL automáticamente usando los modelos GPT de OpenAI, con conocimiento inteligente del esquema y optimización de consultas.

🚀 Perfecto para desarrolladores que usan Cursor AI - Integra directamente en tu flujo de trabajo de desarrollo para obtener información instantánea de la base de datos, exploración de esquemas y análisis de datos sin salir de tu editor de código.

🗃️ Soporte de Bases de Datos

Actualmente soportado:

✅ Microsoft SQL Server (2017+)
✅ SQL Server Express
✅ Azure SQL Database

Próximamente:

🔄 PostgreSQL (en desarrollo)
🔄 MySQL/MariaDB (planificado)
🔄 SQLite (planificado)
🔄 Oracle Database (planificado)

Nota: Esta versión está diseñada específicamente para SQL Server. El soporte para sistemas de bases de datos adicionales está en desarrollo activo y estará disponible en futuras versiones.

🌟 Características

Capacidades principales de la base de datos

🗣️ Lenguaje natural a SQL: Convierte preguntas en inglés a consultas SQL automáticamente
🧠 Conocimiento del esquema: Comprensión inteligente de la estructura de tu base de datos
🔍 Múltiples métodos de consulta: Lenguaje natural, SQL directo y exploración de esquemas
📊 Resultados enriquecidos: Resultados formateados con explicaciones y análisis de consultas
🛡️ Seguridad primero: Validación de consultas integrada y limitación de resultados
🔒 Modo solo SELECT: Alterna entre acceso de solo lectura y acceso completo a la base de datos

Integración para desarrolladores

🔌 Protocolo MCP: Integración nativa con Claude Desktop y Cursor AI
💻 Integración con IDE: Perfecto para flujos de trabajo de desarrollo en Cursor
⚡ Alto rendimiento: Agrupación de conexiones y optimización de consultas
🎯 Registro profesional: Registro integral y manejo de errores

Perfecto para equipos de desarrollo

🚀 Prototipado rápido: Obtén información de la base de datos sin salir de tu editor de código
🔍 Exploración de esquemas: Comprende la estructura de la base de datos mientras programas
🐛 Depuración de datos: Encuentra problemas de datos rápidamente durante el desarrollo
📊 Análisis rápido: Genera informes y perspectivas bajo demanda
🏗️ Diseño de bases de datos: Comprende relaciones y optimiza consultas

🚀 Inicio rápido

Requisitos previos

Python 3.8+
SQL Server Express (o cualquier edición de SQL Server)
ODBC Driver 17 para SQL Server
Clave API de OpenAI (para procesamiento de lenguaje natural)

Instalación

Clona el repositorio

git clone https://github.com/SyedRazaHasnain/chatql-mcp.git
cd chatql-mcp

Crea un entorno virtual

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Instala las dependencias
```
pip install -r requirements.txt
```

Configura el entorno

cp env.example .env

Edita .env con tu configuración:

# Database Configuration
DB_SERVER=localhost\SQLEXPRESS
DB_DATABASE=your_database_name
DB_USERNAME=               # Leave empty for Windows Auth
DB_PASSWORD=               # Leave empty for Windows Auth
DB_DRIVER=ODBC Driver 17 for SQL Server

# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key_here

Conéctate a tu cliente de IA

Elige tu cliente de IA preferido:
- 🖥️ Claude Desktop - Uso general y análisis de datos
- 💻 Cursor AI - Perfecto para flujos de trabajo de desarrollo (¡Recomendado para desarrolladores!)
No necesitas iniciar el servidor manualmente: ¡tu cliente de IA lo iniciará automáticamente!

🛠️ Herramientas disponibles

Cuando estás conectado vía MCP, el servidor proporciona estas potentes herramientas:

1. `execute_natural_language_query`

Transforma lenguaje natural en SQL y ejecuta consultas.

Ejemplo:

Query: "Show me the top 10 customers by total order value"

2. `execute_direct_sql_query`

Ejecuta consultas SQL directamente con validación de seguridad.

Ejemplo:

SELECT TOP 10 CustomerName, SUM(OrderValue) as Total
FROM Customers c JOIN Orders o ON c.ID = o.CustomerID
GROUP BY CustomerName ORDER BY Total DESC

3. `get_table_information`

Obtén información detallada del esquema de cualquier tabla.

4. `list_database_tables`

Explora todas las tablas disponibles en tu base de datos.

5. `get_table_sample_data`

Vista previa de datos de muestra de cualquier tabla.

6. `toggle_select_only_mode` 🔒

Alterna entre modo solo SELECT (solo lectura) y acceso completo a la base de datos.

Ejemplo:

Enable SELECT-only mode: {"enabled": true}
Enable full access: {"enabled": false}

7. `get_security_mode_status` 🔒

Verifica el modo de seguridad actual y los permisos disponibles.

📋 Consultas de ejemplo

Aquí tienes algunas consultas de ejemplo en lenguaje natural que puedes probar:

💻 Flujos de trabajo de desarrollo (Perfecto para Cursor)

"Muéstrame todas las tablas de la base de datos y sus relaciones"
"¿Qué columnas hay en la tabla de usuarios?"
"Dame datos de muestra de la tabla de productos para pruebas"
"Encuentra usuarios creados en la última semana para depuración"
"¿Hay restricciones de clave externa que deba conocer?"
"Muéstrame el esquema de la tabla de pedidos"

📊 Inteligencia de negocios

"¿Cuáles son nuestros 5 productos más vendidos este mes?"
"Muéstrame clientes que no han pedido en los últimos 90 días"
"¿Cuál es el valor promedio de pedido por región?"

🔍 Exploración de datos

"¿Cuántos registros hay en la tabla de clientes?"
"¿Cuáles son las diferentes categorías de productos que tenemos?"
"Muéstrame todos los pedidos realizados ayer"

📈 Análisis

"¿Cuál es nuestra tendencia de ingresos mensuales este año?"
"¿Qué representante de ventas tiene el mejor rendimiento?"
"Encuentra registros de clientes duplicados"

🐛 Depuración y solución de problemas

"Encuentra registros huérfanos en la tabla de elementos de pedido"
"Muéstrame usuarios con direcciones de correo electrónico faltantes"
"¿Cuáles son los códigos de error más comunes en nuestra tabla de registros?"
"Encuentra productos que nunca han sido pedidos"

⚙️ Opciones de configuración

Configuración de la base de datos

DB_SERVER=localhost\SQLEXPRESS    # SQL Server instance
DB_DATABASE=YourDatabase          # Target database
DB_USERNAME=                      # Username (optional for Windows Auth)
DB_PASSWORD=                      # Password (optional for Windows Auth)
DB_DRIVER=ODBC Driver 17 for SQL Server

Configuración de OpenAI

OPENAI_API_KEY=sk-...            # Your OpenAI API key
OPENAI_MODEL=gpt-4               # Model to use
OPENAI_MAX_TOKENS=2000           # Max tokens per request

Configuración del servidor

MCP_SERVER_NAME=chatql-mcp-server
MCP_SERVER_VERSION=1.0.0
LOG_LEVEL=INFO                   # DEBUG, INFO, WARNING, ERROR
MAX_QUERY_RESULTS=100            # Limit query results
QUERY_TIMEOUT=30                 # Query timeout in seconds

Configuración de seguridad

SELECT_ONLY_MODE=false           # Start in SELECT-only mode
ALLOW_MODE_TOGGLE=true           # Allow clients to toggle modes

🔧 Conexión con clientes de IA

Clientes MCP compatibles

Este servidor funciona con cualquier cliente compatible con MCP:

✅ Claude Desktop - Aplicación de escritorio oficial de Anthropic
✅ Cursor AI - Editor de código impulsado por IA (¡Perfecto para desarrollo!)
✅ Otros clientes MCP - Cualquier aplicación que soporte el protocolo MCP

Cómo funciona la conexión MCP

Tu servidor ChatQL utiliza el Model Context Protocol (MCP) con comunicación stdio:

El cliente lee tu configuración → Encuentra los detalles de tu servidor
El cliente inicia tu servidor → Ejecuta python server.py como subproceso
Se comunica vía stdin/stdout → Mensajes JSON a través de flujos estándar
Tu servidor permanece en ejecución → Procesa solicitudes hasta que el cliente cierre

1. Encuentra el archivo de configuración de Claude Desktop

Para usuarios de Windows (Paso a paso):

Presiona Windows Key + R (abre el cuadro de diálogo Ejecutar)
Escribe: %APPDATA% y presiona Enter
Busca la carpeta "Claude" y haz doble clic en ella
Encuentra el archivo: claude_desktop_config.json
- Si el archivo no existe, créalo haciendo clic derecho → Nuevo → Documento de texto
- Nómbralo exactamente: claude_desktop_config.json (¡no .txt!)

Para usuarios de Mac:

Presiona Cmd + Shift + G (abre Ir a carpeta)
Escribe: ~/Library/Application Support/Claude/
Encuentra o crea: claude_desktop_config.json

2. Edita el archivo de configuración

Abre el archivo con el Bloc de notas (Windows) o TextEdit (Mac) y agrega esto:

{
  "mcpServers": {
    "chatql-mcp": {
      "command": "python",
      "args": ["C:/Users/YourUsername/Desktop/mcp/server.py"],
      "env": {
        "DB_SERVER": "localhost\\SQLEXPRESS",
        "DB_DATABASE": "YourDatabase",
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}

🚨 CRÍTICO: Reemplaza estos con TUS valores reales:

C:/Users/YourUsername/Desktop/mcp/server.py → Tu ruta completa real a server.py
YourDatabase → Tu nombre real de base de datos
your-openai-api-key → Tu clave API real de OpenAI

💡 Cómo encontrar la ruta de tu server.py:

Navega a tu carpeta de proyecto (donde guardaste ChatQL)
Haz clic derecho en server.py
Haz clic en "Propiedades" (Windows) o "Obtener información" (Mac)
Copia la ruta completa y pégala en la configuración

3. Inicia Claude Desktop

Guarda tu archivo de configuración (Ctrl+S)
Cierra Claude Desktop por completo (clic derecho en el icono de la bandeja del sistema → Salir)
Vuelve a abrir Claude Desktop (leerá tu nueva configuración)
Busca las herramientas MCP en la interfaz de Claude

4. Prueba tu conexión

Una vez que Claude Desktop se haya reiniciado, prueba estas consultas de prueba:

Consultas en lenguaje natural:

"¿Qué tablas están disponibles en mi base de datos?"
"Muéstrame datos de muestra de la tabla de clientes"
"¿Cuántos registros hay en cada tabla?"

SQL directo:

"Ejecuta este SQL: SELECT TOP 5 * FROM TuTabla"
"Obtén la información del esquema de la tabla de pedidos"

5. Indicadores de éxito

Cuando Claude se conecta correctamente, verás:

🔧 Herramientas MCP listadas en el panel de herramientas de Claude
📊 Respuestas enriquecidas de la base de datos con tablas formateadas
⚡ Ejecución rápida de consultas desde tu base de datos
🛡️ Validaciones de seguridad que bloquean consultas peligrosas

Si la conexión falla, verifica:

✅ La ruta del archivo es correcta en tu configuración
✅ Python está en tu PATH
✅ Todas las dependencias instaladas (pip install -r requirements.txt)
✅ La conexión a la base de datos funciona (verifica tu archivo .env)

🎯 Integración con Cursor AI (Desarrolladores)

¿Por qué usar ChatQL con Cursor?

Transforma tu flujo de trabajo de desarrollo conectando tu base de datos directamente a Cursor AI:

🔍 Exploración instantánea de esquemas - "Muéstrame todas las tablas en esta base de datos"
📊 Análisis rápido de datos - "¿Cuáles son los tipos de usuario más comunes en nuestro sistema?"
🐛 Depuración de problemas de datos - "Encuentra usuarios que tienen pedidos pero no dirección de correo electrónico"
🏗️ Ayuda con diseño de bases de datos - "Muéstrame la relación entre las tablas de usuarios y pedidos"
⚡ Prototipado rápido - Obtén datos de muestra para pruebas sin escribir SQL

Configuración con Cursor

1. Configura Cursor para MCP

Crea o edita tu archivo de configuración de Cursor:

Windows: %APPDATA%\Cursor\User\settings.json Mac: ~/Library/Application Support/Cursor/User/settings.json Linux: ~/.config/Cursor/User/settings.json

Agrega la configuración MCP:

{
  "mcp.servers": {
    "chatql-mcp": {
      "command": "python",
      "args": ["C:/path/to/your/project/server.py"],
      "env": {
        "DB_SERVER": "localhost\\SQLEXPRESS",
        "DB_DATABASE": "YourDatabase",
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}

2. Ejemplos de flujo de trabajo de desarrollo

🔍 Exploración de la base de datos durante el desarrollo

Developer: "What tables do I have available?"
ChatQL: Shows all database tables with schemas

Developer: "Show me the structure of the users table"
ChatQL: Displays columns, data types, constraints, relationships

Developer: "Give me sample data from the orders table"
ChatQL: Returns formatted sample records

🐛 Depuración de problemas de datos

Developer: "Find all users created in the last 7 days"
ChatQL: Converts to SQL and shows recent users

Developer: "Are there any orphaned records in order_items?"
ChatQL: Checks for referential integrity issues

Developer: "Show me users with duplicate email addresses"
ChatQL: Finds and displays duplicate data

📊 Análisis rápido para funciones

Developer: "What's the distribution of user roles in our system?"
ChatQL: Groups and counts user roles

Developer: "Show me the average order value by month"
ChatQL: Generates time-based analytics

Developer: "Which products have never been ordered?"
ChatQL: Finds unused inventory

3. Beneficios específicos de Cursor

🎯 Consciente del contexto: Cursor puede ver tu código y la estructura de la base de datos simultáneamente
⚡ Rápido como un rayo: Sin cambiar entre herramientas de base de datos y tu editor
🧠 Consultas inteligentes: Cursor comprende el contexto de tu código para mejores preguntas
🔄 Desarrollo iterativo: Haz preguntas de seguimiento basadas en los resultados de las consultas
📝 Generación de código: Genera código relacionado con la base de datos basado en información del esquema

4. Ejemplo de sesión de desarrollo

# Working on a user dashboard feature
Developer: "Show me the user table structure"
ChatQL: Returns user schema with all fields

Developer: "What's the relationship between users and their orders?"
ChatQL: Shows JOIN relationships and foreign keys

Developer: "Give me sample data for testing the dashboard"
ChatQL: Returns realistic test data

Developer: "How many users registered each month this year?"
ChatQL: Generates registration analytics

# Cursor can now suggest code based on this database knowledge!

Otros clientes MCP

Este servidor sigue el protocolo MCP estándar y funciona con cualquier cliente compatible con MCP.

🛡️ Seguridad y protección

Protecciones integradas

Validación de consultas: Las operaciones peligrosas (DROP, TRUNCATE) están bloqueadas
Limitación de resultados: Los límites automáticos previenen el agotamiento de memoria
Consultas parametrizadas: Protección contra inyección SQL
Agrupación de conexiones: Conexiones seguras y eficientes a la base de datos
Modo solo SELECT: Modo de solo lectura conmutable para mayor seguridad

🔒 Modo solo SELECT

Una potente característica de seguridad que te permite restringir las operaciones de la base de datos a consultas de solo lectura:

Cómo funciona

Habilitado: Solo se permiten consultas SELECT, todas las operaciones INSERT, UPDATE, DELETE, CREATE, DROP, ALTER están bloqueadas
Deshabilitado: Todas las operaciones SQL están permitidas (con validaciones de seguridad estándar)
Alternar: Se puede activar o desactivar desde el cliente usando la herramienta toggle_select_only_mode

Casos de uso

🔍 Exploración de datos: Navegación segura del contenido de la base de datos sin riesgo de modificación
📊 Informes y análisis: Genera informes con cero riesgo de corrupción de datos
👥 Colaboración en equipo: Permite que los miembros del equipo exploren datos de forma segura
🧪 Desarrollo: Prueba consultas sin afectar los datos de producción
📚 Aprendizaje: Perfecto para aprender SQL sin riesgos de modificación de la base de datos

Integración con el cliente

En Claude Desktop o Cursor:

# Enable SELECT-only mode
Ask: "Enable SELECT-only mode for safety"

# Check current status
Ask: "What is the current security mode?"

# Disable SELECT-only mode
Ask: "Disable SELECT-only mode to allow full access"

Opciones de configuración:

# Start server in SELECT-only mode
SELECT_ONLY_MODE=true

# Disable mode toggle (force current mode)
ALLOW_MODE_TOGGLE=false

Indicadores de seguridad

🔒 RESTRINGIDO: Modo solo SELECT activo
✅ SIN RESTRICCIONES: Modo de acceso completo activo
❌ BLOQUEADO: Operación bloqueada por el modo de seguridad

Mejores prácticas

Comienza con el modo solo SELECT habilitado para entornos nuevos
Usa cuentas de base de datos de solo lectura cuando sea posible
Nunca expongas el servidor a internet
Almacena las credenciales de forma segura usando variables de entorno
Rota regularmente las claves API y las contraseñas de la base de datos

🚨 Solución de problemas

Problemas de conexión a la base de datos

Error: "Nombre de origen de datos no encontrado"

# Install ODBC Driver 17 for SQL Server
# Download from Microsoft's official website

Error: "Login fallido"

Verifica tus credenciales en .env
Para autenticación de Windows, deja usuario/contraseña vacíos
Asegúrate de que SQL Server permita tu método de autenticación

Error: "Error del proveedor Named Pipes"

Verifica que SQL Server esté en ejecución
Comprueba el nombre del servidor (generalmente localhost\SQLEXPRESS)
Habilita TCP/IP en el Administrador de configuración de SQL Server

Problemas con la API de OpenAI

Error: "Clave de API de OpenAI no configurada"

Establece OPENAI_API_KEY en tu archivo .env
Obtén una clave de API desde https://platform.openai.com/

Error: Límite de velocidad

El servidor maneja los límites de velocidad de manera elegante
Considera actualizar tu plan de OpenAI para obtener límites más altos

🧪 Desarrollo

Ejecutar pruebas

# Tests coming soon!
python -m pytest

Estilo de código

# Format code
black .

# Check style
flake8 .

# Type checking
mypy .

🏷️ Gestión de versiones

Este proyecto utiliza un sistema de versionado centralizado con herramientas automatizadas para contribuyentes.

Comandos rápidos de versión

# Check current version
python version_manager.py current

# Bump version for bug fixes (1.0.0 → 1.0.1)
python version_manager.py bump patch

# Bump version for new features (1.0.1 → 1.1.0)
python version_manager.py bump minor

# Bump version for breaking changes (1.1.0 → 2.0.0)
python version_manager.py bump major

Directrices de versionado semántico

PATCH (1.0.1) - Correcciones de errores, parches de seguridad
MINOR (1.1.0) - Nuevas funciones, adiciones de soporte de bases de datos
MAJOR (2.0.0) - Cambios disruptivos, modificaciones de API

Flujo de trabajo completo de lanzamiento

Realiza tus cambios y pruébalos a fondo
Actualiza CHANGELOG.md con tus cambios bajo [Unreleased]

Incrementa la versión usando el tipo apropiado:

python version_manager.py bump minor -m "Added PostgreSQL support"

Envía los cambios incluyendo las etiquetas:
```
git push origin master --tags
```

Detalles del sistema de versiones

✅ Fuente única de verdad: __version__.py
✅ Etiquetado automático de git: Crea etiquetas anotadas (v1.0.0, v1.1.0, etc.)
✅ Auto-commit: Confirma los cambios de versión con mensajes apropiados
✅ Sin actualizaciones manuales: Todos los archivos se sincronizan automáticamente con la versión central

Opciones avanzadas

# Set specific version
python version_manager.py set 1.2.3

# Skip git operations (for testing)
python version_manager.py bump patch --no-commit --no-tag

# Create tag with custom message
python version_manager.py tag -m "Hotfix release"

Nota para contribuyentes: Utiliza siempre el script del gestor de versiones en lugar de editar manualmente los números de versión. Esto garantiza la consistencia en todos los archivos del proyecto.

🤝 Contribuciones

¡Damos la bienvenida a las contribuciones! Consulta CONTRIBUTING.md para obtener detalles sobre:

Configuración del entorno de desarrollo
Estándares de código y mejores prácticas
Proceso de solicitudes de extracción

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

🙏 Agradecimientos

Construido con el Protocolo de Contexto de Modelo (MCP)
Impulsado por Modelos GPT de OpenAI
Utiliza SQLAlchemy para la conectividad de bases de datos

📞 Soporte

🐛 ¿Encontraste un error? Abre un problema
💡 ¿Tienes una solicitud de función? Inicia una discusión
📧 ¿Necesitas ayuda? Consulta nuestra guía de solución de problemas

Hecho con ❤️ por Raza Hasnain

ChatQL MCP Server

Documentación