SQL Sentinel MCP Server

SQL Sentinel MCP Server

A production-ready MCP (Model Context Protocol) server for SQL Server monitoring, diagnostics, and database operations. Built with .NET 9 and Microsoft.Data.SqlClient for native SQL Server connectivity — no ODBC drivers required.

Features

• Session Management — Create, start, stop, drop, and list Extended Events sessions
• Smart Filtering — Filter by application, database, user, duration, host, and text patterns
• Query Fingerprinting — Normalize and group similar queries differing only in literal values
• Sequence Analysis — Trace execution order with timing gaps and cumulative duration
• Deadlock Detection — Capture and analyze XML deadlock reports with victim/process details
• Blocking Analysis — Monitor blocked process events with wait resource and SQL text
• Wait Stats — Query sys.dm_os_wait_stats directly, categorized by type (CPU, I/O, Lock, Memory, etc.)
• Health Check — Comprehensive server diagnostic: slow queries, deadlocks, blocking, wait stats, and insights
• Real-Time Streaming — Stream captured events for a specified duration
• Production-Safe — Auto-excludes noise (sp_reset_connection, SET statements, trace queries)
• Database Operations — List tables, describe schemas, query data, insert, update, and drop tables
• AI-Optimized — Structured JSON output with optional Markdown formatting

Requirements

• SQL Server 2012+ with Extended Events enabled (default)
• Required permissions:

  GRANT ALTER ANY EVENT SESSION TO [your_login];

GRANT VIEW SERVER STATE TO [your_login];

- For blocked process detection:

  EXEC sp_configure 'show advanced options', 1;

RECONFIGURE; EXEC sp_configure 'blocked process threshold', 5; RECONFIGURE;

Installation

Option 1: Docker (Recommended)

No .NET SDK required. Works on any system with Docker installed.

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

Network access: The -i flag is required for stdio transport. Use --network host so the container can reach SQL Server on your host machine. For remote SQL Server, omit --network host and use the accessible hostname in your connection string.

Connection string: Set SQL_SENTINEL_CONNECTION_STRING via -e. All tools read the connection string from this environment variable.

Option 2: .NET Global Tool (NuGet)

Requires .NET 9 SDK or later.

dotnet tool install -g 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" } } } }

Option 3: Build from Source

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

cd sql-sentinel dotnet build

Run directly:

dotnet run --project SqlServer.Profiler.Mcp/

Or publish a self-contained single binary:

# 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

Output will be in bin/Release/net9.0/{runtime}/publish/

Connection Strings

All tools read the connection string from the SQL_SENTINEL_CONNECTION_STRING environment variable. Set it once before starting the server:

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

SQL Authentication:

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

Windows Authentication:

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

Note: Only use TrustServerCertificate=true in development environments with self-signed certificates.

For production, always use TrustServerCertificate=false with a valid SSL certificate.

Azure SQL:

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

MCP Tools Reference

Session Lifecycle

Event Retrieval

Diagnostics

Permissions

Database Operations

Usage Examples

Quick Debug Session

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")

Find N+1 Queries

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

Trace Specific Operation

Agent: sqlsentinel_analyze_sequence(

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

Deadlock Detection

Agent: sqlsentinel_quick_capture(

sessionName: "deadlock_monitor", eventTypes: "Deadlock" )

// Wait for deadlocks to occur

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

Blocking Analysis

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" )

Server Health Check

Agent: sqlsentinel_health_check(

sessionName: "my_session", slowQueryThresholdMs: 1000, responseFormat: "Markdown" )

Database Operations

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" )

Wait Stats (No Session Required)

Agent: sqlsentinel_get_wait_stats(

topN: 20, responseFormat: "Markdown" )

Query Fingerprinting

Queries are normalized to group similar ones:

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

Noise Filtering

Default excluded patterns (when excludeNoise=true):

• sp_reset_connection — Connection pool reset
• SET TRANSACTION ISOLATION LEVEL — Session setup
• SET NOCOUNT, SET ANSI_* — Client configuration
• sp_trace_*, fn_trace_* — Trace system queries

Supported Event Types

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

Project Structure

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