SQL Sentinel MCP Server

Un servidor MCP (Model Context Protocol) listo para producción para el monitoreo, diagnóstico y operaciones de bases de datos de SQL Server. Construido con .NET 9 y Microsoft.Data.SqlClient para conectividad nativa con SQL Server: no se requieren controladores ODBC.

Características

• Gestión de sesiones — Crear, iniciar, detener, eliminar y listar sesiones de Extended Events

• Filtrado inteligente — Filtrar por aplicación, base de datos, usuario, duración, host y patrones de texto

• Huella digital de consultas — Normalizar y agrupar consultas similares que difieren solo en valores literales

• Análisis de secuencias — Rastrear el orden de ejecución con intervalos de tiempo y duración acumulada

• Detección de interbloqueos — Capturar y analizar informes XML de interbloqueos con detalles de víctima/procesos

• Análisis de bloqueos — Monitorear eventos de procesos bloqueados con recurso de espera y texto SQL

• Estadísticas de espera — Consultar sys.dm_os_wait_stats directamente, clasificadas por tipo (CPU, E/S, Bloqueo, Memoria, etc.)

• Comprobación de estado — Diagnóstico completo del servidor: consultas lentas, interbloqueos, bloqueos, estadísticas de espera e información

• Transmisión en tiempo real — Transmitir eventos capturados durante un período especificado

• Seguro para producción — Excluye automáticamente ruido (sp_reset_connection, sentencias SET, consultas de seguimiento)

• Operaciones de bases de datos — Listar tablas, describir esquemas, consultar datos, insertar, actualizar y eliminar tablas

• Optimizado para IA — Salida JSON estructurada con formato Markdown opcional

Related MCP server: mysql-mcp-server

Requisitos

• SQL Server 2012+ con Extended Events habilitado (por defecto)

• Permisos requeridos:

  GRANT ALTER ANY EVENT SESSION TO [your_login];
  GRANT VIEW SERVER STATE TO [your_login];

• Para la detección de procesos bloqueados:

  EXEC sp_configure 'show advanced options', 1;
  RECONFIGURE;
  EXEC sp_configure 'blocked process threshold', 5;
  RECONFIGURE;

Instalación

Opción 1: Docker (Recomendado)

No se requiere SDK de .NET. Funciona en cualquier sistema con Docker instalado.

docker pull ghcr.io/tkmawarire/sql-sentinel-mcp:latest

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "sql-sentinel": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--network", "host",
               "-e", "SQL_SENTINEL_CONNECTION_STRING=Server=localhost;Database=master;User Id=sa;Password=YourPassword;TrustServerCertificate=true",
               "ghcr.io/tkmawarire/sql-sentinel-mcp:latest"]
    }
  }
}

Claude Code

claude mcp add sql-sentinel \
  -e SQL_SENTINEL_CONNECTION_STRING="Server=localhost;Database=master;User Id=sa;Password=YourPassword;TrustServerCertificate=true" \
  -- docker run -i --rm --network host \
  -e SQL_SENTINEL_CONNECTION_STRING \
  ghcr.io/tkmawarire/sql-sentinel-mcp:latest

Acceso a la red: La opción -i es necesaria para el transporte stdio. Usa --network host para que el contenedor pueda alcanzar SQL Server en tu máquina host. Para SQL Server remoto, omite --network host y usa el nombre de host accesible en tu cadena de conexión.

Cadena de conexión: Configura SQL_SENTINEL_CONNECTION_STRING mediante -e. Todas las herramientas leen la cadena de conexión de esta variable de entorno.

Opción 2: Herramienta global .NET (NuGet)

Requiere SDK de .NET 9 o posterior.

dotnet tool install -g Neofenyx.SqlSentinel.Mcp

{
  "mcpServers": {
    "sql-sentinel": {
      "command": "sql-sentinel-mcp",
      "env": {
        "SQL_SENTINEL_CONNECTION_STRING": "Server=localhost;Database=master;User Id=sa;Password=YourPassword;TrustServerCertificate=true"
      }
    }
  }
}

Opción 3: Compilar desde el código fuente

git clone https://github.com/tkmawarire/sql-sentinel.git
cd sql-sentinel
dotnet build

Ejecutar directamente:

dotnet run --project SqlServer.Profiler.Mcp/

O publicar un binario único autocontenido:

# Windows
dotnet publish SqlServer.Profiler.Mcp/ -c Release -r win-x64 --self-contained

# Linux
dotnet publish SqlServer.Profiler.Mcp/ -c Release -r linux-x64 --self-contained

# macOS (Apple Silicon)
dotnet publish SqlServer.Profiler.Mcp/ -c Release -r osx-arm64 --self-contained

# macOS (Intel)
dotnet publish SqlServer.Profiler.Mcp/ -c Release -r osx-x64 --self-contained

La salida estará en bin/Release/net9.0/{runtime}/publish/

Cadenas de conexión

Todas las herramientas leen la cadena de conexión de la variable de entorno SQL_SENTINEL_CONNECTION_STRING. Configúrala una vez antes de iniciar el servidor:

export SQL_SENTINEL_CONNECTION_STRING="Server=localhost;Database=master;User Id=sa;Password=YourPassword;TrustServerCertificate=false;Encrypt=true"

Autenticación de SQL:

Server=localhost;Database=master;User Id=sa;Password=YourPassword;TrustServerCertificate=false;Encrypt=true

Autenticación de Windows:

Server=localhost;Database=master;Integrated Security=true;TrustServerCertificate=false;Encrypt=true

Nota: Usa TrustServerCertificate=true solo en entornos de desarrollo con certificados autofirmados. Para producción, usa siempre TrustServerCertificate=false con un certificado SSL válido.

Azure SQL:

Server=yourserver.database.windows.net;Database=yourdb;User Id=user;Password=password;Encrypt=true

Referencia de herramientas MCP

Ciclo de vida de sesiones

Recuperación de eventos

Diagnósticos

Permisos

Operaciones de bases de datos

Ejemplos de uso

Sesión de depuración rápida

Agent: sqlsentinel_quick_capture(
    sessionName: "debug_api",
    applications: "MyWebApp",
    minDurationMs: 100
)

// User triggers the slow operation

Agent: sqlsentinel_get_events(
    sessionName: "debug_api",
    sortBy: "DurationDesc",
    limit: 20
)

Agent: sqlsentinel_drop_session(sessionName: "debug_api")

Encontrar consultas N+1

Agent: sqlsentinel_quick_capture(
    sessionName: "n_plus_one_check",
    databases: "OrdersDB"
)

// User loads a page

Agent: sqlsentinel_get_stats(
    sessionName: "n_plus_one_check",
    groupBy: "QueryFingerprint"
)

// Look for queries with high execution counts

Rastrear operación específica

Agent: sqlsentinel_analyze_sequence(
    sessionName: "my_session",
    correlationId: "order-12345",
    responseFormat: "Markdown"
)

Detección de interbloqueos

Agent: sqlsentinel_quick_capture(
    sessionName: "deadlock_monitor",
    eventTypes: "Deadlock"
)

// Wait for deadlocks to occur

Agent: sqlsentinel_get_deadlocks(
    sessionName: "deadlock_monitor",
    responseFormat: "Markdown"
)

Análisis de bloqueos

Agent: sqlsentinel_quick_capture(
    sessionName: "blocking_check",
    eventTypes: "BlockedProcess"
)

// Requires: sp_configure 'blocked process threshold', 5

Agent: sqlsentinel_get_blocking(
    sessionName: "blocking_check",
    responseFormat: "Markdown"
)

Comprobación de estado del servidor

Agent: sqlsentinel_health_check(
    sessionName: "my_session",
    slowQueryThresholdMs: 1000,
    responseFormat: "Markdown"
)

Operaciones de bases de datos

Agent: sqlsentinel_list_tables()

Agent: sqlsentinel_describe_table(
    name: "dbo.Products"
)

Agent: sqlsentinel_read_data(
    sql: "SELECT TOP 10 * FROM dbo.Products ORDER BY CreatedDate DESC"
)

Estadísticas de espera (no se requiere sesión)

Agent: sqlsentinel_get_wait_stats(
    topN: 20,
    responseFormat: "Markdown"
)

Huella digital de consultas

Las consultas se normalizan para agrupar las similares:

-- These become one fingerprint:
SELECT * FROM Users WHERE id = 123
SELECT * FROM Users WHERE id = 456

-- Fingerprint: abc123:SELECT * FROM Users WHERE id = ?
-- Execution count: 2

Filtrado de ruido

Patrones excluidos por defecto (cuando excludeNoise=true):

• sp_reset_connection — Restablecimiento del grupo de conexiones

• SET TRANSACTION ISOLATION LEVEL — Configuración de sesión

• SET NOCOUNT, SET ANSI_* — Configuración del cliente

• sp_trace_*, fn_trace_* — Consultas de seguimiento del sistema

Tipos de eventos admitidos

SqlBatchCompleted, RpcCompleted, SqlStatementCompleted, SpStatementCompleted, Attention, ErrorReported, Deadlock, BlockedProcess, LoginEvent, SchemaChange, Recompile, AutoStats

Estructura del proyecto

sql-profiler-mcp/
├── .github/
│   └── workflows/
│       ├── docker.yml                     # Build & push multi-arch Docker images
│       └── publish-mcp-registry.yml       # Publish NuGet + MCP registry
├── .mcp/
│   └── server.json                        # MCP manifest (NuGet + OCI packages)
├── SqlServer.Profiler.Mcp/                # Main MCP server (stdio transport)
│   ├── SqlServer.Profiler.Mcp.csproj
│   ├── Program.cs                         # Entry point, DI setup, MCP config
│   ├── Models/
│   │   ├── ProfilerModels.cs              # Records, enums, data models
│   │   └── DbOperationResult.cs           # Result model for CRUD operations
│   ├── Services/
│   │   ├── ProfilerService.cs             # Core Extended Events logic
│   │   ├── QueryFingerprintService.cs     # SQL normalization & fingerprinting
│   │   ├── WaitStatsService.cs            # DMV-based wait stats analysis
│   │   ├── SessionConfigStore.cs          # In-memory session config storage
│   │   └── EventStreamingService.cs       # Real-time event streaming
│   ├── Utilities/
│   │   └── SqlInputValidator.cs           # SQL input validation & escaping
│   └── Tools/
│       ├── SessionManagementTools.cs      # Session lifecycle tools (6)
│       ├── EventRetrievalTools.cs         # Event retrieval tools (5)
│       ├── DiagnosticTools.cs             # Diagnostic tools (4)
│       ├── PermissionTools.cs             # Permission tools (2)
│       └── DatabaseTools.cs               # Database CRUD tools (7)
├── SqlServer.Profiler.Mcp.Api/            # Debug REST API (Swagger on port 5100)
│   ├── SqlServer.Profiler.Mcp.Api.csproj
│   ├── Program.cs
│   ├── Controllers/
│   │   └── ProfilerController.cs
│   ├── Models/
│   │   └── RequestModels.cs
│   └── appsettings.json
├── SqlServer.Profiler.Mcp.Cli/            # Debug CLI (REPL + script mode)
│   ├── SqlServer.Profiler.Mcp.Cli.csproj
│   └── Program.cs
├── SqlServer.Profiler.Mcp.Tests/          # xUnit tests for core MCP library (228 tests)
│   └── ...
├── SqlServer.Profiler.Mcp.Api.Tests/      # xUnit tests for API project (29 tests)
│   └── ...
├── Dockerfile                             # Multi-stage build (bookworm-slim)
├── .dockerignore
├── SqlServer.Profiler.Mcp.slnx           # Solution file
├── CLAUDE.md
├── CONTRIBUTING.md
└── README.md

Desarrollo

Requisitos previos

• .NET 9 SDK

• Instancia de SQL Server 2012+ (local, Docker o remota)

• Docker (opcional, para compilaciones de contenedores)

Clonar y compilar

git clone https://github.com/tkmawarire/sql-sentinel.git
cd sql-sentinel
dotnet restore
dotnet build

Ejecutar el servidor MCP localmente

dotnet run --project SqlServer.Profiler.Mcp/

El servidor se comunica a través de stdio usando el protocolo MCP. Conéctalo a un cliente MCP (Claude Desktop, Claude Code, etc.) para uso interactivo.

Uso de la API de depuración

El proyecto de API proporciona un envoltorio REST alrededor de todas las herramientas MCP con Swagger UI para pruebas manuales.

dotnet run --project SqlServer.Profiler.Mcp.Api/

• Swagger UI: http://localhost:5100/

• Configura la cadena de conexión mediante la variable de entorno SQL_SENTINEL_CONNECTION_STRING

Uso de la CLI de depuración

El proyecto CLI proporciona un REPL interactivo y modo de script para probar herramientas directamente.

# Interactive REPL mode
dotnet run --project SqlServer.Profiler.Mcp.Cli/

# List all available tools
dotnet run --project SqlServer.Profiler.Mcp.Cli/ list

# Get help for a specific tool
dotnet run --project SqlServer.Profiler.Mcp.Cli/ help sqlsentinel_quick_capture

# Execute a single tool
dotnet run --project SqlServer.Profiler.Mcp.Cli/ call sqlsentinel_list_sessions

Establece la variable de entorno SQL_SENTINEL_CONNECTION_STRING antes de ejecutar.

Compilación de Docker

docker build -t sql-sentinel-mcp:test .
docker run -i --rm --network host sql-sentinel-mcp:test

Arquitectura

Patrones clave

• Inyección de dependencias mediante Microsoft.Extensions.Hosting

• Transporte stdio — stdout está reservado para el protocolo MCP; todo el registro se envía a stderr

• Autodescubrimiento de herramientas — las herramientas MCP se descubren desde el ensamblado mediante WithToolsFromAssembly()

• Prefijo de sesión XE — todas las sesiones creadas llevan el prefijo mcp_sentinel_

• Dos formas de eventos — eventos estándar (consulta, inicio de sesión, recompilación) con campos tipados, y eventos con carga útil XML (interbloqueo, bloqueo) analizados desde XML de Extended Events

Añadir una nueva herramienta MCP

1. Crea un método public static en el archivo correspondiente bajo Tools/ (o crea un archivo nuevo)

2. Decóralo con [McpServerTool(Name = "sqlsentinel_your_tool")] y [Description("...")]

3. Añade parámetros con atributos [Description("...")] — se convierten en el esquema de entrada de la herramienta

4. Inyecta servicios mediante parámetros de método (p. ej., IProfilerService, IWaitStatsService)

5. Devuelve una cadena (JSON o Markdown) — el framework se encarga de envolver la respuesta MCP

[McpServerTool(Name = "sqlsentinel_example")]
[Description("Description shown to AI agents")]
public static async Task<string> Example(
    IProfilerService profilerService,
    [Description("Optional filter")] string? filter = null)
{
    var connectionString = ConnectionStringResolver.Resolve();
    // Implementation
    return JsonSerializer.Serialize(result);
}

Solución de problemas

"Permiso denegado" al crear la sesión

GRANT ALTER ANY EVENT SESSION TO [your_login];
GRANT VIEW SERVER STATE TO [your_login];

"Error de inicio de sesión"

• Comprueba las credenciales de la cadena de conexión

• Para la autenticación de Windows, asegúrate de que el proceso se ejecute con el usuario correcto

• Para Azure SQL, asegúrate de que el firewall permita tu IP

No se capturaron eventos

1. Verifica que la sesión esté EN EJECUCIÓN (sqlsentinel_list_sessions)

2. Comprueba que los filtros no sean demasiado restrictivos

3. Verifica que la base de datos/aplicación de destino esté generando consultas

4. Comprueba que minDurationMs no esté filtrando todo

No hay eventos de interbloqueo

• Asegúrate de que la sesión se haya creado con eventTypes: "Deadlock"

• Los interbloqueos deben ocurrir realmente mientras la sesión está en ejecución

No hay eventos de bloqueo

• Asegúrate de que el umbral de procesos bloqueados esté configurado: sp_configure 'blocked process threshold', 5

• Asegúrate de que la sesión se haya creado con eventTypes: "BlockedProcess"

• El bloqueo debe superar el umbral configurado (segundos)

Tiempo de espera agotado al leer eventos

Los búferes circulares grandes con muchos eventos pueden ser lentos de analizar. Usa:

• Filtros de tiempo para acotar la ventana

• Aumenta el tiempo de espera del comando en el código si es necesario

Notas de seguridad

• La variable de entorno SQL_SENTINEL_CONNECTION_STRING contiene credenciales: asegúrala adecuadamente

• No dejes sesiones ejecutándose indefinidamente en producción

• El texto de las consultas puede contener datos sensibles

• Otorga solo los permisos mínimos necesarios

Contribuciones

Consulta CONTRIBUTING.md para obtener las pautas sobre cómo enviar incidencias y pull requests.

Licencia

MIT