SQL Sentinel MCP Server

SQL Sentinel MCP Server

SQL Server の監視、診断、データベース操作を行う、本番環境対応の MCP（Model Context Protocol）サーバーです。.NET 9 と Microsoft.Data.SqlClient で構築されており、ネイティブな SQL Server 接続に対応しています。ODBC ドライバーは不要です。

特長

• セッション管理 — Extended Events セッションの作成、開始、停止、削除、一覧表示
• スマートフィルタリング — アプリケーション、データベース、ユーザー、実行時間、ホスト、テキストパターンでフィルタリング
• クエリフィンガープリント — リテラル値のみが異なる類似クエリを正規化してグループ化
• シーケンス分析 — 実行順序を、時間間隔や累積実行時間とともに追跡
• デッドロック検出 — デッドロックの XML レポートを取得して分析し、犠牲プロセスやプロセスの詳細を表示
• ブロッキング分析 — 待機リソースと SQL テキストを含む、ブロックされたプロセスのイベントを監視
• 待機統計 — sys.dm_os_wait_stats を直接クエリし、種類（CPU、I/O、ロック、メモリなど）ごとに分類
• ヘルスチェック — スロークエリ、デッドロック、ブロッキング、待機統計、インサイトを網羅するサーバー診断
• リアルタイムストリーミング — 指定した時間にわたって取得したイベントをストリーミング
• 本番環境に安全 — ノイズ（sp_reset_connection、SET ステートメント、トレースクエリ）を自動的に除外
• データベース操作 — テーブルの一覧表示、スキーマの説明、データのクエリ、テーブルへの挿入・更新・削除
• AI 向けに最適化 — オプションの Markdown 形式に対応した、構造化 JSON 出力

必要条件

• Extended Events が有効な SQL Server 2012 以降（デフォルトで有効）
• 必要な権限：

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

• ブロックされたプロセスの検出に必要な権限：

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

インストール

オプション 1：Docker（推奨）

.NET SDK は不要です。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

ネットワークアクセス：stdio トランスポートには -i フラグが必要です。コンテナーからホストマシン上の SQL Server に接続できるよう、--network host を使用してください。リモート SQL Server の場合は --network host を省略し、接続文字列でアクセス可能なホスト名を使用してください。

接続文字列：-e を使って SQL_SENTINEL_CONNECTION_STRING を設定してください。すべてのツールは、この環境変数から接続文字列を読み取ります。

オプション 2：.NET グローバルツール（NuGet）

.NET 9 SDK 以降が必要です。

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

オプション 3：ソースからビルド

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

直接実行する場合：

dotnet run --project SqlServer.Profiler.Mcp/

または、依存関係を含む単一のバイナリとして発行します：

# 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

出力先は bin/Release/net9.0/{runtime}/publish/ です。

接続文字列

すべてのツールは、SQL_SENTINEL_CONNECTION_STRING 環境変数から接続文字列を読み取ります。サーバーの起動前に、一度設定してください：

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

SQL 認証：

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

Windows 認証：

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

注： 自己署名証明書を使用する開発環境でのみ、TrustServerCertificate=true を使用してください。 本番環境では、必ず有効な SSL 証明書とともに TrustServerCertificate=false を使用してください。

Azure SQL：

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

MCP ツールのリファレンス

セッションのライフサイクル

ツール	説明
sqlsentinel_create_session	フィルターを指定して Extended Events セッションを作成（未開始）
sqlsentinel_start_session	既存のセッションでイベントの取得を開始
sqlsentinel_stop_session	イベントの取得を停止（イベントは保持されます）
sqlsentinel_drop_session	セッションを削除し、すべてのイベントを破棄
sqlsentinel_list_sessions	MCP が作成したすべてのセッションを、状態とバッファー使用量とともに一覧表示
sqlsentinel_quick_capture	セッションを作成し、1 ステップで開始

イベントの取得

ツール	説明
sqlsentinel_get_events	フィルタリング、並べ替え、重複排除を行ってキャプチャしたイベントを取得します
sqlsentinel_get_stats	フィンガープリント、データベース、アプリ、ログインごとに集計した統計情報を取得します
sqlsentinel_analyze_sequence	実行時間と間隔を含めてクエリの実行シーケンスを分析します
sqlsentinel_get_connection_info	データベース、アプリ、ログイン、セッション、ブロッキング情報を一覧表示します
sqlsentinel_stream_events	指定した期間（1～300秒）のイベントをリアルタイムでキャプチャします

診断

ツール	説明
sqlsentinel_get_deadlocks	デッドロックイベントを、被害者、プロセス、ロック、SQL テキストとともに取得します
sqlsentinel_get_blocking	ブロックされたプロセスのイベントを、待機リソースと SQL テキストとともに取得します
sqlsentinel_get_wait_stats	タイプ別に分類した sys.dm_os_wait_stats をクエリします（セッション不要）
sqlsentinel_health_check	スロークエリ、デッドロック、ブロッキング、待機統計、分析情報を含む包括的なレポートを作成します

権限

ツール	説明
sqlsentinel_check_permissions	現在のログイン権限と、ブロックされたプロセスのしきい値設定を確認します
sqlsentinel_grant_permissions	ログインに必要な権限を付与します（sysadmin が必要）

データベース操作

ツール	説明
sqlsentinel_list_tables	データベース内のすべてのユーザーテーブルを一覧表示します（スキーマ名付き）
sqlsentinel_describe_table	列、インデックス、制約、外部キーを含む詳細なテーブルスキーマを表示します
sqlsentinel_create_table	CREATE TABLE ステートメントで新しいテーブルを作成します
sqlsentinel_insert_data	INSERT ステートメントでデータを挿入します
sqlsentinel_read_data	SELECT クエリを実行し、結果を返します
sqlsentinel_update_data	UPDATE ステートメントでデータを更新します
sqlsentinel_drop_table	DROP TABLE ステートメントでテーブルを削除します

使用例

クイックデバッグセッション

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 クエリを見つける

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

特定の操作を追跡する

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

デッドロックの検出

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

// Wait for deadlocks to occur

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

ブロッキングの分析

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

サーバーのヘルスチェック

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

データベース操作

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

待機統計（セッション不要）

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

クエリのフィンガープリンティング

類似したクエリをグループ化するため、クエリは正規化されます。

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

ノイズのフィルタリング

デフォルトで除外されるパターン（excludeNoise=true の場合）：

• sp_reset_connection — 接続プールのリセット
• SET TRANSACTION ISOLATION LEVEL — セッションのセットアップ
• SET NOCOUNT、SET ANSI_* — クライアントの設定
• sp_trace_*、fn_trace_* — トレースシステムのクエリ

サポートされているイベントタイプ

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

プロジェクト構成

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

開発

前提条件

• .NET 9 SDK
• SQL Server 2012 以降のインスタンス（ローカル、Docker、またはリモート）
• Docker（任意、コンテナーのビルド用）

クローンとビルド

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

MCP サーバーをローカルで実行する

dotnet run --project SqlServer.Profiler.Mcp/

サーバーは MCP プロトコルを使用して stdio 経由で通信します。対話的に使用するには、MCP クライアント（Claude Desktop、Claude Code など）に接続してください。

デバッグ API の使用

API プロジェクトは、手動テスト用の Swagger UI を備えた、すべての MCP ツールの REST ラッパーを提供します。

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

• Swagger UI：http://localhost:5100/
• 環境変数 SQL_SENTINEL_CONNECTION_STRING で接続文字列を設定します

デバッグ CLI の使用

CLI プロジェクトは、ツールを直接テストするための対話型 REPL とスクリプトモードを提供します。

# 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

実行する前に、環境変数 SQL_SENTINEL_CONNECTION_STRING を設定してください。

Docker ビルド

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

アーキテクチャ

主なパターン

• 依存性注入：Microsoft.Extensions.Hosting を使用します
• stdio トランスポート — stdout は MCP プロトコル用に予約されており、すべてのログは stderr に出力されます
• ツールの自動検出 — WithToolsFromAssembly() を介して、アセンブリから MCP ツールが検出されます
• XE セッションのプレフィックス — 作成されるすべてのセッションに mcp_sentinel_ というプレフィックスが付きます
• 2 種類のイベント形式 — 型付きフィールドを持つ標準イベント（query、login、recompile）と、Extended Events XML から解析される XML ペイロードイベント（deadlock、blocking）

新しい MCP ツールの追加

1. Tools/ の適切なファイルに public static メソッドを作成します（または新しいファイルを作成します）
2. [McpServerTool(Name = "sqlsentinel_your_tool")] と [Description("...")] を付与します
3. [Description("...")] 属性を使ってパラメーターを追加します。これらがツールの入力スキーマになります
4. メソッドのパラメーターを介してサービスを注入します（例：IProfilerService、IWaitStatsService）
5. 文字列（JSON または Markdown）を返します。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);
}

トラブルシューティング

セッション作成時の「Permission denied」

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

「Login failed」

• 接続文字列の認証情報を確認します
• Windows 認証の場合、プロセスが正しいユーザーで実行されていることを確認します
• Azure SQL の場合、ファイアウォールで IP アドレスが許可されていることを確認します

イベントがキャプチャされない

1. セッションが RUNNING であることを確認します（sqlsentinel_list_sessions）
2. フィルターの条件が厳しすぎないことを確認します
3. 対象のデータベース／アプリでクエリが生成されていることを確認します
4. minDurationMs によってすべてのイベントが除外されていないことを確認します

デッドロックイベントがない

• セッションが eventTypes: "Deadlock" を指定して作成されていることを確認します
• セッションの実行中に実際にデッドロックが発生する必要があります

ブロッキングイベントがない

• blocked process threshold が設定されていることを確認します：sp_configure 'blocked process threshold', 5
• セッションが eventTypes: "BlockedProcess" を指定して作成されていることを確認します
• ブロッキングが設定されたしきい値（秒）を超える必要があります

イベントの読み取り時にタイムアウトする

イベントが多数含まれる大きなリングバッファーは、解析に時間がかかることがあります。次の方法を使用してください。

• 時間フィルターを使って対象期間を絞り込みます
• 必要に応じて、コード内のコマンドタイムアウトを延長します

セキュリティに関する注意事項

• SQL_SENTINEL_CONNECTION_STRING 環境変数には認証情報が含まれています。適切に保護してください
• 本番環境でセッションを無期限に実行したままにしないでください
• クエリテキストに機密データが含まれている可能性があります
• 必要最小限の権限を付与してください

貢献

問題やプルリクエストの提出方法については、CONTRIBUTING.md を参照してください。

ライセンス

MIT