MSSQL

Interactuar con bases de datos de Microsoft SQL Server para ejecutar consultas y analizar datos empresariales.

GitHub
39
Prueba este MCPPatrocinado

Documentación

Servidor MCP de MSSQL

English | 中文

Descripción general

El servidor MCP de MSSQL proporciona capacidades de interacción con bases de datos e inteligencia empresarial. Este servidor permite ejecutar consultas SQL, analizar datos empresariales y generar automáticamente memorandos de información empresarial.
Consulte el SQLite del sitio web oficial para realizar modificaciones y adaptarlo a MSSQL.

Construido sobre el SDK oficial de MCP Python (FastMCP), compatible con la especificación MCP 2025-06-18: salida de herramientas estructurada (structuredContent), anotaciones de herramientas, plantillas de recursos y confirmación de escritura basada en elicitación.

Aspectos destacados:

  • Multi-base de datos — monta conexiones de desarrollo/ensayo/producción en un solo servidor; cada herramienta acepta un parámetro opcional database, cada conexión con su propia configuración de readonly / query_timeout / max_rows / confirm_writes
  • Procedimientos almacenados — lista firmas y ejecuta procedimientos con recopilación completa de múltiples conjuntos de resultados
  • Plantillas de recursos — schema://{database}/{schema}/{table} sirve estructuras de tablas bajo demanda sin consumir tokens de esquema de herramientas en cada turno
  • Salvaguardas de seguridad — lista blanca de SQL, modo de solo lectura, límites de filas, tiempos de espera de consultas, confirmación opcional por elicitación antes de escrituras

Componentes

  • read_query
    • Ejecuta consultas SELECT / WITH con salida estructurada (columnas / filas / recuento_de_filas / truncado), limitado por max_rows
  • write_query
    • Ejecuta consultas INSERT, UPDATE, DELETE o MERGE, devuelve el recuento de filas afectadas
  • create_table
    • Crea nuevas tablas en la base de datos
  • list_tables
    • Obtiene una lista de todas las tablas en la base de datos (esquema + nombre de tabla)
  • list_views
    • Obtiene una lista de todas las vistas en la base de datos
  • describe_table
    • Muestra el esquema completo de una tabla específica (tipo, anulable, valor predeterminado, clave primaria, identidad, claves foráneas, índices)
  • list_databases
    • Lista las conexiones de base de datos configuradas (nombre, solo_lectura, es_predeterminada)
  • list_procedures
    • Lista procedimientos almacenados con firmas de parámetros
  • execute_procedure
    • Ejecuta un procedimiento almacenado (admite múltiples conjuntos de resultados)
  • append_insight
    • Agrega nueva información empresarial al recurso de memorando

Recursos

  • memo://insights — un memorando de información empresarial en vivo, actualizado en tiempo real mediante append_insight
  • schema://{schema}/{table} — estructura de tablas de la base de datos predeterminada (JSON: columnas / clave primaria / identidad / claves foráneas / índices)
  • schema://{database}/{schema}/{table} — estructura de tablas de una conexión de base de datos con nombre

Las plantillas de recursos se obtienen bajo demanda: a diferencia de los esquemas de herramientas, no se reenvían al LLM en cada turno, lo que mantiene las conversaciones largas ágiles.

Seguridad

Todo el SQL pasa por validación estática antes de la ejecución:

  • read_query solo acepta una única declaración SELECT / WITH y rechaza cualquier escritura o palabra clave EXEC (bloquea, por ejemplo, WITH c AS (...) DELETE FROM t)

  • write_query utiliza una lista blanca (solo INSERT / UPDATE / DELETE / MERGE); EXEC, DROP, TRUNCATE, ALTER son rechazados

  • Los lotes de múltiples declaraciones (separados por ;) son rechazados

  • trusted_connection: true cambia a autenticación integrada de Windows (la cadena de conexión usa Trusted_Connection=yes, sin necesidad de nombre de usuario/contraseña); false mantiene el inicio de sesión de cuenta SQL configurado

  • readonly: true deshabilita todas las operaciones de escritura, incluidos los procedimientos almacenados (son cajas negras que pueden escribir)

  • Los nombres de procedimientos almacenados se validan estrictamente como identificadores de 1 a 3 partes con puntos antes de incrustarse en {CALL ...}

  • Los resultados se truncan en max_rows filas; las consultas se abortan después de query_timeout segundos

  • Con confirm_writes: true, todas las operaciones que cambian el estado (escrituras de write_query, create_table, execute_procedure) primero solicitan confirmación al usuario mediante elicitación de MCP

    ⚠️ Limitación importante: la confirmación depende de que el cliente implemente el protocolo de Elicitación de MCP. Los clientes sin soporte de elicitación (por ejemplo, TraeWork / Cursor ...) omiten la confirmación y ejecutan escrituras directamente — lo que significa que confirm_writes: true no proporciona protección en dichos clientes (se registra una advertencia de omisión en el servidor). Para una protección de escritura confiable en cualquier cliente, use readonly: true en su lugar (bloquea todas las escrituras independientemente de las capacidades del cliente)

  • Los comentarios y literales de cadena se eliminan antes de la validación, por lo que no pueden usarse para evadir las comprobaciones

Demostración

La tabla de la base de datos es la siguiente. Los nombres de las columnas no están estandarizados, y la IA los relacionará por sí misma. Los errores durante la ejecución de SQL se autocorregirán.

Table

La siguiente es la demostración.

Demo

Entorno operativo

  • Python 3.10+
  • Packages
    • pyodbc>=4.0.39
    • pydantic>=2.0.0
    • mcp>=1.9.0,<2.0.0
  • ODBC Driver 17 / 18 for SQL Server

Uso

Instalar paquetes

Desde el código fuente:

git clone <this repo>
CD /d ~/mssql-mcp  
pip install -r requirements.txt

O como paquete (pip >= 21.3):

pip install .

Configuración

Cree config.json. Formato de base de datos única:

{
    "database": {
        "driver": "ODBC Driver 17 for SQL Server",
        "server": "server ip",
        "database": "db name",
        "username": "username",
        "password": "password",
        "trusted_connection": false,
        "readonly": false,
        "query_timeout": 30,
        "max_rows": 200,
        "confirm_writes": false
    },
    "server": {
        "name": "mssql-manager",
        "version": "0.2.0"
    }
}

Formato de múltiples bases de datos (recomendado — cada conexión tiene configuración independiente, por ejemplo, producción permanece en solo lectura):

{
    "databases": {
        "default": { "server": "localhost", "database": "dev_db", "...": "..." },
        "prod":    { "server": "10.0.0.5", "database": "prod_db", "readonly": true, "...": "..." }
    },
    "default_database": "default",
    "server": { "name": "mssql-manager", "version": "0.2.0" }
}

Nombres de conexión y conexión predeterminada: las claves en databases son los nombres de conexión — el LLM pasa una de ellas como el parámetro database para cambiar de conexión. Las claves son arbitrarias (no tiene que llamar a una de ellas default). default_database decide qué conexión se usa cuando database no se pasa, resuelto en este orden:

  1. Si default_database: "xxx" está configurado explícitamente, use la conexión llamada xxx
  2. De lo contrario, si existe una conexión llamada default, úsela
  3. De lo contrario, use la primera conexión en el diccionario

Recomendado: configure explícitamente default_database y también mantenga una conexión literalmente llamada default como red de seguridad — de esta manera, agregar nuevas conexiones (que pueden terminar primero en el orden de iteración) no cambiará silenciosamente la predeterminada.

Orden de búsqueda del archivo de configuración: variable de entorno MSSQL_MCP_CONFIG → config.json junto a server.py → config.json en el directorio de trabajo.

Campos opcionales (por conexión):

CampoPredeterminadoDescripción
readonlyfalseModo de solo lectura: bloquea todas las operaciones de escritura (incluidos los procedimientos)
query_timeout30Tiempo de espera de consulta en segundos
max_rows200Máximo de filas por conjunto de resultados; las filas adicionales se truncan
confirm_writesfalseSolicitar confirmación al usuario (elicitación) antes de todas las operaciones que cambian el estado (escrituras / CREATE TABLE / procedimientos); requiere soporte de Elicitación del cliente — los clientes no compatibles (por ejemplo, TraeWork / Cursor) ejecutan directamente; para protección estricta use readonly
encrypt(ninguno)Cifrado ODBC, para Driver 18 (true / false)
trust_server_certificatefalseConfiar en certificados autofirmados, útil con Driver 18

Variables de entorno:

VariablePredeterminadoDescripción
MSSQL_MCP_CONFIG(ninguno)Ruta a un archivo de configuración alternativo
MSSQL_MCP_LOG_LEVELINFONivel de registro (DEBUG / INFO / WARNING / ERROR)

Configuración del cliente (Claude Desktop / Cursor / Windsurf, etc.)

Los clientes stdio principales (Claude Desktop, Cursor, Windsurf, Cline, etc.) comparten el mismo formato JSON de mcpServers. Tome Claude Desktop como ejemplo — para otros clientes, agregue la misma entrada a su archivo de configuración MCP:

# add to claude_desktop_config.json. Note：use your path  
{
    "mcpServers": {
        "mssql": {
            "command": "python",
            "args": [
                # your path，e.g.："C:\\mssql-mcp\\src\\server.py"
                "~/server.py"
            ]
        }
    }
}

Si se instala como paquete, el comando puede ser simplemente mssql-mcp (sin argumentos necesarios).

Inspector de MCP

# Note：use your path  
npx -y @modelcontextprotocol/inspector python C:\\mssql-mcp\\src\\server.py

Ejecutar pruebas

pip install pytest
python -m pytest tests -q
  • tests/test_validation.py — validación de SQL / nombres de procedimientos (no requiere base de datos)
  • tests/test_config.py — análisis de configuración: compatibilidad con base de datos única heredada, múltiples bases de datos, casos de error (no requiere base de datos)
  • tests/test_integration.py — de extremo a extremo contra la base de datos en src/config.json (las escrituras solo tocan objetos de prueba dedicados de mcp_upgrade_*, limpiados automáticamente)

Estructura del proyecto

mssql-mcp
├── .git
├── .gitignore
├── LICENSE
├── README.md
├── README_en.md
├── README_zh.md
├── imgs
│   ├── table.png
│   └── demo.gif
├── pyproject.toml        (packaging: src/ is installed as the mssql_mcp package)
├── requirements.txt
├── src
│   ├── __init__.py
│   ├── config.json      (gitignored, local database config)
│   └── server.py
└── tests
    ├── test_validation.py
    ├── test_config.py
    └── test_integration.py

Licencia

Licencia MIT