SQL Sentinel MCP Server

Ein produktionsreifer MCP-Server (Model Context Protocol) für SQL Server-Überwachung, Diagnose und Datenbankoperationen. Erstellt mit .NET 9 und Microsoft.Data.SqlClient für native SQL Server-Konnektivität — keine ODBC-Treiber erforderlich.

Features

• Sitzungsverwaltung — Extended Events-Sitzungen erstellen, starten, stoppen, löschen und auflisten

• Intelligente Filterung — Nach Anwendung, Datenbank, Benutzer, Dauer, Host und Textmustern filtern

• Query-Fingerprinting — Ähnliche Abfragen, die sich nur in Literalwerten unterscheiden, normalisieren und gruppieren

• Sequenzanalyse — Ausführungsreihenfolge mit Zeitlücken und kumulativer Dauer nachverfolgen

• Deadlock-Erkennung — XML-Deadlock-Berichte mit Opfer-/Prozessdetails erfassen und analysieren

• Blocking-Analyse — Blockierte Prozessereignisse mit Wartevorgang-Ressource und SQL-Text überwachen

• Wait Stats — sys.dm_os_wait_stats direkt abfragen, nach Typ kategorisiert (CPU, I/O, Sperre, Speicher usw.)

• Health Check — Umfassende Serverdiagnose: langsame Abfragen, Deadlocks, Blocking, Wait Stats und Erkenntnisse

• Echtzeit-Streaming — Erfasste Ereignisse für eine angegebene Dauer streamen

• Produktionssicher — Blendet Rauschen automatisch aus (sp_reset_connection, SET-Anweisungen, Abfragen zur Ablaufverfolgung)

• Datenbankoperationen — Tabellen auflisten, Schemas beschreiben, Daten abfragen, einfügen, aktualisieren und Tabellen löschen

• KI-optimiert — Strukturierte JSON-Ausgabe mit optionaler Markdown-Formatierung

Related MCP server: mysql-mcp-server

Anforderungen

• SQL Server 2012+ mit aktivierten Extended Events (Standard)

• Erforderliche Berechtigungen:

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

• Für die Erkennung blockierter Prozesse:

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

Installation

Option 1: Docker (Empfohlen)

Kein .NET SDK erforderlich. Funktioniert auf jedem System mit installiertem Docker.

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

Netzwerkzugriff: Das Flag -i ist für den Stdio-Transport erforderlich. Verwenden Sie --network host, damit der Container SQL Server auf Ihrem Host-Rechner erreichen kann. Für einen entfernten SQL Server lassen Sie --network host weg und verwenden Sie den erreichbaren Hostnamen in Ihrer Verbindungszeichenfolge.

Verbindungszeichenfolge: Setzen Sie SQL_SENTINEL_CONNECTION_STRING über -e. Alle Tools lesen die Verbindungszeichenfolge aus dieser Umgebungsvariable.

Option 2: .NET Global Tool (NuGet)

Erfordert .NET 9 SDK oder höher.

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

Option 3: Aus dem Quellcode erstellen

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

Direkt ausführen:

dotnet run --project SqlServer.Profiler.Mcp/

Oder eine eigenständige einzelne Binärdatei veröffentlichen:

# 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

Ausgabe befindet sich in bin/Release/net9.0/{runtime}/publish/

Verbindungszeichenfolgen

Alle Tools lesen die Verbindungszeichenfolge aus der Umgebungsvariable SQL_SENTINEL_CONNECTION_STRING. Setzen Sie sie einmal, bevor Sie den Server starten:

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

SQL-Authentifizierung:

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

Windows-Authentifizierung:

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

Hinweis: Verwenden Sie TrustServerCertificate=true nur in Entwicklungsumgebungen mit selbstsignierten Zertifikaten. Verwenden Sie in der Produktion immer TrustServerCertificate=false mit einem gültigen SSL-Zertifikat.

Azure SQL:

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

Referenz der MCP-Tools

Sitzungslebenszyklus

Ereignisabruf

Diagnose

Berechtigungen

Datenbankoperationen

Verwendungsbeispiele

Schnelle Debug-Sitzung

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

N+1-Abfragen finden

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

Bestimmten Vorgang nachverfolgen

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

Deadlock-Erkennung

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

// Wait for deadlocks to occur

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

Blocking-Analyse

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

Datenbankoperationen

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 (keine Sitzung erforderlich)

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

Query-Fingerprinting

Abfragen werden normalisiert, um ähnliche zu gruppieren:

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

Rauschfilterung

Standardmäßig ausgeschlossene Muster (wenn excludeNoise=true):

• sp_reset_connection — Zurücksetzen des Verbindungspools

• SET TRANSACTION ISOLATION LEVEL — Sitzungseinrichtung

• SET NOCOUNT, SET ANSI_* — Clientkonfiguration

• sp_trace_*, fn_trace_* — Systemabfragen zur Ablaufverfolgung

Unterstützte Ereignistypen

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

Projektstruktur

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

Entwicklung

Voraussetzungen

• .NET 9 SDK

• SQL Server 2012+-Instanz (lokal, Docker oder remote)

• Docker (optional, für Container-Builds)

Klonen und Erstellen

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

MCP-Server lokal ausführen

dotnet run --project SqlServer.Profiler.Mcp/

Der Server kommuniziert über stdio mit dem MCP-Protokoll. Verbinden Sie ihn zur interaktiven Nutzung mit einem MCP-Client (Claude Desktop, Claude Code usw.).

Verwenden der Debug-API

Das API-Projekt bietet einen REST-Wrapper um alle MCP-Tools mit Swagger-UI für manuelle Tests.

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

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

• Konfigurieren Sie die Verbindungszeichenfolge über die Umgebungsvariable SQL_SENTINEL_CONNECTION_STRING

Verwenden der Debug-CLI

Das CLI-Projekt bietet einen interaktiven REPL- und Skriptmodus zum direkten Testen der Tools.

# 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

Setzen Sie die Umgebungsvariable SQL_SENTINEL_CONNECTION_STRING, bevor Sie es ausführen.

Docker-Build

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

Architektur

Wichtige Muster

• Abhängigkeitsinjektion über Microsoft.Extensions.Hosting

• Stdio-Transport — stdout ist für das MCP-Protokoll reserviert; die gesamte Protokollierung erfolgt über stderr

• Automatische Tool-Erkennung — MCP-Tools werden aus der Assembly über WithToolsFromAssembly() ermittelt

• XE-Sitzungspräfix — Alle erstellten Sitzungen erhalten das Präfix mcp_sentinel_

• Zwei Ereignisformen — Standardereignisse (Abfrage, Anmeldung, Neukompilierung) mit typisierten Feldern und XML-Payload-Ereignisse (Deadlock, Blocking), die aus Extended Events-XML geparst werden

Hinzufügen eines neuen MCP-Tools

1. Erstellen Sie eine public static-Methode in der entsprechenden Datei unter Tools/ (oder erstellen Sie eine neue Datei)

2. Dekorieren Sie sie mit [McpServerTool(Name = "sqlsentinel_your_tool")] und [Description("...")]

3. Fügen Sie Parameter mit [Description("...")]-Attributen hinzu — sie werden zum Eingabeschema des Tools

4. Injizieren Sie Dienste über Methodenparameter (z. B. IProfilerService, IWaitStatsService)

5. Geben Sie einen String zurück (JSON oder Markdown) — das Framework übernimmt die MCP-Antwortumwicklung

[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);
}

Fehlerbehebung

„Permission denied" beim Erstellen der Sitzung

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

„Login fehlgeschlagen"

• Überprüfen Sie die Anmeldedaten in der Verbindungszeichenfolge

• Stellen Sie bei Windows-Authentifizierung sicher, dass der Prozess unter dem richtigen Benutzer läuft

• Stellen Sie bei Azure SQL sicher, dass die Firewall Ihre IP-Adresse zulässt

Keine Ereignisse erfasst

1. Stellen Sie sicher, dass die Sitzung AUSGEFÜHRT wird (sqlsentinel_list_sessions)

2. Prüfen Sie, ob die Filter nicht zu restriktiv sind

3. Stellen Sie sicher, dass die Zieldatenbank/-App Abfragen generiert

4. Prüfen Sie, ob minDurationMs nicht alles herausfiltert

Keine Deadlock-Ereignisse

• Stellen Sie sicher, dass die Sitzung mit eventTypes: "Deadlock" erstellt wurde

• Deadlocks müssen tatsächlich auftreten, während die Sitzung läuft

Keine Blocking-Ereignisse

• Stellen Sie sicher, dass blocked process threshold konfiguriert ist: sp_configure 'blocked process threshold', 5

• Stellen Sie sicher, dass die Sitzung mit eventTypes: "BlockedProcess" erstellt wurde

• Blocking muss den konfigurierten Schwellenwert (in Sekunden) überschreiten

Timeout beim Lesen von Ereignissen

Große Ringpuffer mit vielen Ereignissen können beim Parsen langsam sein. Verwenden Sie:

• Zeitfilter, um den Zeitraum einzugrenzen

• Erhöhen Sie bei Bedarf das Befehls-Timeout im Code

Sicherheitshinweise

• Die Umgebungsvariable SQL_SENTINEL_CONNECTION_STRING enthält Anmeldedaten — sichern Sie sie angemessen

• Lassen Sie Sitzungen in der Produktion nicht unbegrenzt laufen

• Abfragetexte können sensible Daten enthalten

• Erteilen Sie nur die mindestens erforderlichen Berechtigungen

Mitwirken

Siehe CONTRIBUTING.md für Richtlinien zum Einreichen von Issues und Pull Requests.

Lizenz

MIT