SQL Server MCP Client

SQL Server MCP クライアント

0.0.5 での破壊的変更： セキュリティ上の理由から、クエリとストアドプロシージャの実行ツールはデフォルトで無効になりました。以前のデフォルト設定を利用していた場合は、対応する環境変数を "true" に設定して、明示的に有効にする必要があります。

• DatabaseConfiguration__EnableExecuteQuery
• DatabaseConfiguration__EnableExecuteStoredProcedure
• DatabaseConfiguration__EnableStartQuery
• DatabaseConfiguration__EnableStartStoredProcedure

設定例については、Claude Desktop / Claude Code の設定をご覧ください。

Model Context Protocol（MCP）を実装した、包括的な Microsoft SQL Server クライアントです。このサーバーは、シンプルな MCP インターフェイスを通じて、クエリ実行、スキーマの検出、ストアドプロシージャの管理など、幅広い SQL Server 機能を提供します。

概要

SQL Server MCP クライアントは、Model Context Protocol C# SDK（github.com/modelcontextprotocol/csharp-sdk）を使用して .NET Core で構築されています。SQL Server データベースに対する SQL クエリの実行、ストアドプロシージャの管理、テーブル一覧の取得、包括的なスキーマ情報の取得を行うツールを提供します。このサーバーは軽量でありながら強力で、実用的なデータベース機能を備えた堅牢な MCP サーバーの作成方法を示します。マシンに直接デプロイすることも、Docker コンテナーとしてデプロイすることもできます。

MCP クライアントは、次のいずれかのモードで動作します。

• データベースモード：接続文字列に特定のデータベースが指定されている場合、そのデータベースのコンテキスト内でのみ操作を利用できます
• サーバーモード：接続文字列にデータベースが指定されていない場合、すべてのデータベースを対象としたサーバー全体の操作を利用できます

機能

データベースの基本操作

• 接続先の SQL Server データベースで SQL クエリを実行
• スキーマと行数の情報を含む、すべてのテーブルの一覧を取得
• 特定のテーブルの詳細なスキーマ情報を取得
• ストアドプロシージャを包括的に管理・実行

ストアドプロシージャのサポート

• パラメーターの検出：テーブル形式または JSON Schema 形式で詳細なパラメーター情報を取得
• 型安全な実行：パラメーターのメタデータに基づき、JSON から SQL の型へ自動変換
• 豊富なメタデータ：入力／出力パラメーター、デフォルト値、データ型の制約に対応
• データベース間操作：異なるデータベースをまたいでプロシージャを実行（サーバーモード）

高度な機能

• JSON Schema 出力：検証ツールと互換性のあるパラメーターのメタデータ
• 大文字と小文字を区別しないパラメーター：@ プレフィックスを正規化し、柔軟なパラメーター名に対応
• SQL Server 機能の検出：機能を包括的に報告
• 2 モードアーキテクチャ：単一データベースと複数データベースの両方のシナリオに最適化
• タイムアウトの設定：デフォルトおよび操作ごとのタイムアウトを制御し、実行時管理ツールも提供
• バックグラウンドセッション管理：セッションベースの監視により、時間のかかるクエリやプロシージャを実行
• 実行時間の計測：クエリとストアドプロシージャの結果に、経過時間と SQL Server が報告する実行時間を自動で表示
• クエリのプロファイリング：パフォーマンス分析用に、テーブルごとの IO 統計情報と実際の XML 実行プランを任意で取得
• 影響を受けた行数：DML 操作によって影響を受けた行数を自動で報告

セキュリティと設定

• セキュリティのため、ツールの有効化を設定可能
• 環境変数による設定
• 標準化されたエラーメッセージを用いた包括的なエラー処理
• SQL Server のメタデータに基づく入力検証

はじめに

前提条件

• .NET 10.0 SDK（ローカル開発／デプロイ用）
• Docker（コンテナーのデプロイ用）

ビルド手順（開発用）

ソースからプロジェクトをビルドする場合：

1. このリポジトリをクローンします。

   git clone https://github.com/aadversteeg/mssqlclient-mcp-server.git
   

2. ソースディレクトリに移動します。

   cd mssqlclient-mcp-server/src
   

3. プロジェクトをビルドします。

   dotnet build
   

4. 単体テストを実行します。

   dotnet test
   

統合テストの実行

統合テストでは、実際の SQL Server インスタンスに対して MCP サーバーを検証します。テストフレームワークが Docker コンテナーを自動的に管理します。空いているポート（14330～14339 の範囲）を見つけ、一意の名前で SQL Server コンテナーを起動し、すべてのテストを実行した後、完了時にコンテナーを削除します。

前提条件は、Docker が実行されていることだけです。

cd tst
dotnet test --filter "TestType=Integration"

統合テストでは、ツールのメタデータ検証に加え、クエリ実行、テーブル一覧表示、スキーマ取得の機能テストを含む、データベースモード（Database= を含む接続文字列）とサーバーモード（Database= を含まない接続文字列）の両方を検証します。

統合テストは、GitHub Actions タブから手動で実行できる Integration Tests ワークフローを通じて、CI でも自動的に実行されます。

Docker サポート

Docker Hub

SQL Server MCP Client は Docker Hub で利用できます。

# Pull the latest version
docker pull aadversteeg/mssqlclient-mcp-server:latest

Docker イメージの手動ビルド

Docker イメージを自分でビルドする必要がある場合：

# Navigate to the repository root
cd mssqlclient-mcp-server

# Build the Docker image
docker build -f src/Core.Infrastructure.McpServer/Dockerfile -t mssqlclient-mcp-server:latest src/

# Run the locally built image
docker run -d --name mssql-mcp -e "MSSQL_CONNECTIONSTRING=Server=your_server;Database=your_db;User Id=your_user;Password=your_password;TrustServerCertificate=True;" mssqlclient-mcp-server:latest

ローカルレジストリへのプッシュ

ローカルレジストリにプッシュするには：

# Build the Docker image
docker build -f src/Core.Infrastructure.McpServer/Dockerfile -t localhost:5000/mssqlclient-mcp-server:latest src/

# Push to local registry
docker push localhost:5000/mssqlclient-mcp-server:latest

ローカルレジストリの使用

ポート 5000 で実行中のローカルレジストリにイメージをプッシュした場合は、そこからプルできます。

# Pull from local registry
docker pull localhost:5000/mssqlclient-mcp-server:latest

.NET ツール

SQL Server MCP Client は、NuGet の .NET グローバルツールとして利用できます。

インストール

dotnet tool install --global Ave.McpServer.MsSqlClient

実行

ave-mcpserver-mssqlclient

一度限りの実行（永続的なインストールなし）

.NET 10 SDK では、dotnet tool exec を使用して、ツールをグローバルにインストールせずに実行できます。

dotnet tool exec -y ave.mcpserver.mssqlclient

-y フラグを指定すると、プロンプトが自動的に承認されます。ツールはローカルにキャッシュされますが、PATH には追加されません。

Claude Desktop / Claude Code の設定

設定ファイルの mcpServers セクションにサーバー設定を追加します。

デフォルトでは、読み取り専用のツール（テーブルの一覧表示、スキーマの表示、ストアドプロシージャの一覧表示）のみが有効です。クエリとストアドプロシージャの実行を有効にするには、対応する環境変数に "true" を設定します。

設定	説明	デフォルト
DatabaseConfiguration__EnableExecuteQuery	execute_query / execute_query_in_database ツールを有効にします	false
DatabaseConfiguration__EnableExecuteStoredProcedure	execute_stored_procedure / execute_stored_procedure_in_database ツールを有効にします	false
DatabaseConfiguration__EnableStartQuery	start_query / start_query_in_database セッションツールを有効にします	false
DatabaseConfiguration__EnableStartStoredProcedure	start_stored_procedure / start_stored_procedure_in_database セッションツールを有効にします	false
DatabaseConfiguration__MaxCellOutputLength	クエリ結果の各セルに表示する最大文字数です。この値を超える場合は ... で切り詰められます。切り詰めを無効にするには 0 を設定します。	40

.NET ツールの使用

.NET 10 SDK が必要です。この方法では、初回使用時にツールが自動的にダウンロードされ、以降の実行時に最新バージョンへ更新されます。

"mssql": {
  "command": "dotnet",
  "args": [
    "tool",
    "exec",
    "-y",
    "ave.mcpserver.mssqlclient"
  ],
  "env": {
    "MSSQL_CONNECTIONSTRING": "Data Source=localhost;Integrated Security=True;MultipleActiveResultSets=True;TrustServerCertificate=True;",
    "DatabaseConfiguration__EnableExecuteQuery": "true",
    "DatabaseConfiguration__EnableExecuteStoredProcedure": "true",
    "DatabaseConfiguration__EnableStartQuery": "true",
    "DatabaseConfiguration__EnableStartStoredProcedure": "true"
  }
}

グローバルインストールを使用

.NET 10 SDK が必要です。ツールを一度インストールすれば、直接使用できます。

dotnet tool install --global Ave.McpServer.MsSqlClient

"mssql": {
  "command": "ave-mcpserver-mssqlclient",
  "env": {
    "MSSQL_CONNECTIONSTRING": "Data Source=localhost;Integrated Security=True;MultipleActiveResultSets=True;TrustServerCertificate=True;",
    "DatabaseConfiguration__EnableExecuteQuery": "true",
    "DatabaseConfiguration__EnableExecuteStoredProcedure": "true",
    "DatabaseConfiguration__EnableStartQuery": "true",
    "DatabaseConfiguration__EnableStartStoredProcedure": "true"
  }
}

更新するには：dotnet tool update --global Ave.McpServer.MsSqlClient

MCP プロトコルの使用

クライアントの統合

アプリケーションから SQL Server MCP Client に接続するには：

1. Model Context Protocol C# SDK または MCP 対応クライアントを使用します
2. サーバーのエンドポイントに接続するようクライアントを設定します
3. 以下で説明する利用可能なツールを呼び出します

利用可能なツール

利用可能なツールは、サーバーが動作しているモードによって異なります。一部のツールは両方のモードで利用できます。

共通ツール（両方のモードで利用可能）

server_capabilities

接続されている SQL Server インスタンスの機能と特性に関する詳細情報を返します。

リクエスト例：

{
  "name": "server_capabilities",
  "parameters": {}
}

Server Mode でのレスポンス例：

{
  "version": "Microsoft SQL Server 2019",
  "majorVersion": 15,
  "minorVersion": 0,
  "buildNumber": 4123,
  "edition": "Enterprise Edition",
  "isAzureSqlDatabase": false,
  "isAzureVmSqlServer": false,
  "isOnPremisesSqlServer": true,
  "toolMode": "server",
  "features": {
    "supportsPartitioning": true,
    "supportsColumnstoreIndex": true,
    "supportsJson": true,
    "supportsInMemoryOLTP": true,
    "supportsRowLevelSecurity": true,
    "supportsDynamicDataMasking": true,
    "supportsDataCompression": true,
    "supportsDatabaseSnapshots": true,
    "supportsQueryStore": true,
    "supportsResumableIndexOperations": true,
    "supportsGraphDatabase": true,
    "supportsAlwaysEncrypted": true,
    "supportsExactRowCount": true,
    "supportsDetailedIndexMetadata": true,
    "supportsTemporalTables": true
  }
}

このツールは次の用途に便利です：

• SQL Server インスタンスで利用できる機能を確認する
• 互換性の問題をデバッグする
• 使用されるクエリパターンを把握する
• サーバーモードとデータベースモードのどちらであるかを確認する

get_command_timeout

現在のタイムアウト設定を返します。

リクエスト例：

{
  "name": "get_command_timeout",
  "parameters": {}
}

レスポンス例：

{
  "defaultCommandTimeoutSeconds": 30,
  "connectionTimeoutSeconds": 15,
  "maxConcurrentSessions": 10,
  "sessionCleanupIntervalMinutes": 60,
  "totalToolCallTimeoutSeconds": 120,
  "timestamp": "2024-12-19 10:30:45 UTC"
}

set_command_timeout

新しい操作すべてに適用される既定のコマンドタイムアウトを更新します。

注記： TotalToolCallTimeoutSeconds が設定されている場合、有効なタイムアウトは、この値と残りの合計タイムアウトのうち小さい方になります。これにより、操作が合計ツール呼び出しタイムアウトの上限内に完了します。

パラメーター：

• timeoutSeconds（必須）：新しいタイムアウト（秒）（1～3600）

リクエスト例：

{
  "name": "set_command_timeout",
  "parameters": {
    "timeoutSeconds": 120
  }
}

レスポンス例：

{
  "message": "Default command timeout updated successfully",
  "oldTimeoutSeconds": 30,
  "newTimeoutSeconds": 120,
  "note": "This change only affects new operations. Existing sessions will continue with their original timeout settings.",
  "timestamp": "2024-12-19 10:31:00 UTC"
}

セッション管理ツール

これらのツールを使用すると、バックグラウンドセッションを介して、長時間実行されるクエリやストアドプロシージャを管理できます。特に、操作が TotalToolCallTimeoutSeconds の上限を超える場合や、複数の操作を同時に実行する必要がある場合に便利です。

get_session_status

実行中のクエリまたはストアドプロシージャのセッション状態を確認します。

パラメーター：

• sessionId（必須）：確認するセッション ID

リクエスト例：

{
  "name": "get_session_status",
  "parameters": {
    "sessionId": 12345
  }
}

レスポンス例：

{
  "sessionId": 12345,
  "type": "query",
  "query": "SELECT * FROM LargeTable",
  "databaseName": "Northwind",
  "startTime": "2024-12-19 10:30:00 UTC",
  "endTime": "2024-12-19 10:35:23 UTC",
  "duration": "323.5 seconds",
  "status": "completed",
  "isRunning": false,
  "rowCount": 1500000,
  "error": null,
  "timeoutSeconds": 600,
  "serverElapsedTimeMs": 323000,
  "serverCpuTimeMs": 18500,
  "rowsAffected": null,
  "ioStats": [
    { "table": "LargeTable", "logicalReads": 45230, "physicalReads": 120, "readAheadReads": 44800 }
  ],
  "executionPlanXml": null
}

以下のフィールドは、利用可能な場合に含まれます（それ以外の場合は null）。

• serverElapsedTimeMs / serverCpuTimeMs：SQL Server 側の処理時間（常に取得されます）
• rowsAffected：DML 操作によって影響を受けた行の合計数（常に取得されます）
• ioStats：テーブルごとの IO 統計情報（開始ツールで includeIoStats が true に設定されている場合のみ）
• executionPlanXml：実際の XML 実行プラン（開始ツールで includeExecutionPlan が true に設定されている場合のみ）

get_session_results

完了済みまたは実行中のクエリ／ストアドプロシージャのセッション結果を取得します。

パラメーター：

• sessionId（必須）：結果を取得するセッション ID
• maxRows（任意）：返す行の最大数

リクエスト例：

{
  "name": "get_session_results",
  "parameters": {
    "sessionId": 12345,
    "maxRows": 100
  }
}

レスポンス例：

{
  "sessionId": 12345,
  "type": "query",
  "status": "completed",
  "rowCount": 1500000,
  "results": "| CustomerID | CompanyName | ContactName |\n| ---------- | ----------- | ----------- |\n| ALFKI | Alfreds Futterkiste | Maria Anders |\n...\n... (showing first 100 rows of 1500000 total)",
  "maxRowsApplied": 100,
  "serverElapsedTimeMs": 323000,
  "serverCpuTimeMs": 18500,
  "rowsAffected": null,
  "ioStats": [
    { "table": "Customers", "logicalReads": 42, "physicalReads": 0, "readAheadReads": 0 }
  ],
  "executionPlanXml": null
}

stop_session

実行中のクエリまたはストアドプロシージャのセッションを停止します。

パラメーター：

• sessionId（必須）：停止するセッション ID

リクエスト例：

{
  "name": "stop_session",
  "parameters": {
    "sessionId": 12345
  }
}

レスポンス例：

{
  "sessionId": 12345,
  "status": "cancelled",
  "message": "Session cancelled successfully",
  "timestamp": "2024-12-19 10:32:15 UTC"
}

list_sessions

すべてのクエリおよびストアドプロシージャのセッションを一覧表示します。

パラメーター：

• status（任意）：状態で絞り込みます。「all」（既定値）、「running」、「completed」のいずれかです。

リクエスト例：

{
  "name": "list_sessions",
  "parameters": {
    "status": "running"
  }
}

レスポンス例：

{
  "filter": "running",
  "totalSessions": 2,
  "sessions": [
    {
      "sessionId": 12345,
      "type": "query",
      "query": "SELECT * FROM LargeTable...",
      "databaseName": "Northwind",
      "startTime": "2024-12-19 10:30:00 UTC",
      "duration": "45.2 seconds",
      "status": "running",
      "isRunning": true,
      "rowCount": 0,
      "hasError": false
    },
    {
      "sessionId": 12346,
      "type": "storedprocedure",
      "query": "GenerateMonthlyReport",
      "databaseName": "Sales",
      "startTime": "2024-12-19 10:25:00 UTC",
      "duration": "320.1 seconds",
      "status": "running",
      "isRunning": true,
      "rowCount": 0,
      "hasError": false
    }
  ],
  "timestamp": "2024-12-19 10:30:45 UTC"
}

データベースモードのツール

接続文字列で特定のデータベースに接続している場合、次のツールを利用できます。

execute_query

接続されている SQL Server データベースで SQL クエリを実行します。

パラメーター：

• query（必須）：実行する SQL クエリ。
• timeoutSeconds（任意）：コマンドのタイムアウト（秒）。既定のタイムアウトを上書きします。
• includeIoStats（任意）：テーブルごとの IO 統計情報を含めます。既定値は false です。
• includeExecutionPlan（任意）：実際の XML 実行プランを含めます。既定値は false です。
• maxCellOutputLength（任意）：セルごとに表示する最大文字数。この値を超える文字列は ... で切り詰められます。切り詰めを無効にするには 0 を設定します。指定しない場合はサーバーの既定値（MaxCellOutputLength、既定値 40）が使用されます。

リクエスト例：

{
  "name": "execute_query",
  "parameters": {
    "query": "SELECT TOP 5 * FROM Customers",
    "includeIoStats": true
  }
}

レスポンス例：

| CustomerID | CompanyName                      | ContactName        |
| ---------- | -------------------------------- | ------------------ |
| ALFKI      | Alfreds Futterkiste              | Maria Anders       |
| ANATR      | Ana Trujillo Emparedados y h...  | Ana Trujillo       |
| ANTON      | Antonio Moreno Taquería          | Antonio Moreno     |
| AROUT      | Around the Horn                  | Thomas Hardy       |
| BERGS      | Berglunds snabbköp               | Christina Berglund |

Total rows: 5
Execution time: 42ms (server: 38ms, CPU: 12ms)
IO stats: Customers (logical: 12, physical: 0, read-ahead: 0)

実行時間

実行時間の行には、次の情報が表示されます。

• 合計実行時間：クライアント側で計測した実時間（ネットワーク遅延と結果の読み取りを含む）
• サーバー経過時間：クエリ実行について SQL Server が報告した時間
• CPU 時間：SQL Server で消費された CPU 時間

SQL Server のタイミング情報を取得できない場合は、クライアント側の時間のみが表示されます：Execution time: 42ms

実行時間は、すべての実行ツールの出力に常に含まれます。

IO 統計

includeIoStats を true に設定すると、テーブルごとの IO 統計が出力に追加されます。

IO stats: Customers (logical: 12, physical: 0, read-ahead: 0), Orders (logical: 42, physical: 3, read-ahead: 40)

アクセスした各テーブルについて、次の情報が表示されます。

• 論理読み取り：バッファーキャッシュから読み取ったページ数
• 物理読み取り：ディスクから読み取ったページ数
• 先読み読み取り：クエリ用にキャッシュへ配置されたページ数

IO 統計は、欠落しているインデックスや非効率なクエリプランの特定に役立ちます。

実行プラン

includeExecutionPlan を true に設定すると、実際の XML 実行プランが出力の末尾に含まれます。

Execution plan:
<ShowPlanXML xmlns="http://schemas.microsoft.com/sqlserver/2004/07/showplan" ...>...</ShowPlanXML>

XML プランは .sqlplan ファイルに保存し、SQL Server Management Studio または Azure Data Studio で開いて視覚的に分析できます。

影響を受けた行数

結果行を返さない DML 操作（INSERT、UPDATE、DELETE）では、出力に次の情報が含まれます。

Query executed successfully. No results returned.
Rows affected: 5
Execution time: 12ms (server: 8ms, CPU: 2ms)

影響を受けた行数の報告は常に有効で、オーバーヘッドはありません。

これらのプロファイリング機能（includeIoStats、includeExecutionPlan）は、execute_query_in_database、execute_stored_procedure、execute_stored_procedure_in_database、およびすべてのセッション開始ツールでも利用できます。

list_tables

接続中の SQL Server データベースにあるすべてのテーブルを、スキーマと行数の情報とともに一覧表示します。

リクエストの例：

{
  "name": "list_tables",
  "parameters": {}
}

レスポンスの例：

Available Tables:

Schema | Table Name | Row Count
------ | ---------- | ---------
dbo    | Customers  | 91
dbo    | Products   | 77
dbo    | Orders     | 830
dbo    | Employees  | 9

get_table_schema

接続中の SQL Server データベースからテーブルのスキーマを取得します。

パラメーター：

• tableName（必須）：スキーマ情報を取得するテーブルの名前。

リクエストの例：

{
  "name": "get_table_schema",
  "parameters": {
    "tableName": "Customers"
  }
}

レスポンスの例：

Schema for table: Customers

Column Name | Data Type | Max Length | Is Nullable
----------- | --------- | ---------- | -----------
CustomerID  | nchar     | 5          | NO
CompanyName | nvarchar  | 40         | NO
ContactName | nvarchar  | 30         | YES
ContactTitle| nvarchar  | 30         | YES
Address     | nvarchar  | 60         | YES
City        | nvarchar  | 15         | YES
Region      | nvarchar  | 15         | YES
PostalCode  | nvarchar  | 10         | YES
Country     | nvarchar  | 15         | YES
Phone       | nvarchar  | 24         | YES
Fax         | nvarchar  | 24         | YES

list_stored_procedures

現在のデータベースにあるすべてのストアドプロシージャを、詳細情報とともに一覧表示します。

リクエストの例：

{
  "name": "list_stored_procedures",
  "parameters": {}
}

レスポンスの例：

Available Stored Procedures in 'Northwind':

Schema   | Procedure Name                  | Parameters | Last Execution    | Execution Count | Created Date
-------- | ------------------------------- | ---------- | ----------------- | --------------- | -------------------
dbo      | GetCustomerOrders               | 2          | 2024-01-15 10:30:00 | 145           | 2023-12-01 09:00:00
dbo      | UpdateProductPrice              | 3          | 2024-01-14 16:45:00 | 89            | 2023-11-15 14:30:00
dbo      | CreateNewCustomer               | 5          | N/A               | N/A           | 2024-01-10 11:20:00

get_stored_procedure_definition

ストアドプロシージャの SQL 定義を取得します。

パラメーター：

• procedureName（必須）：ストアドプロシージャの名前。

リクエストの例：

{
  "name": "get_stored_procedure_definition",
  "parameters": {
    "procedureName": "GetCustomerOrders"
  }
}

get_stored_procedure_parameters

ストアドプロシージャのパラメーター情報を、テーブル形式または JSON Schema 形式で取得します。

パラメーター：

• procedureName（必須）：ストアドプロシージャの名前。
• format（任意）：出力形式。「table」（既定値）または「json」。

リクエストの例（テーブル形式）：

{
  "name": "get_stored_procedure_parameters",
  "parameters": {
    "procedureName": "CreateNewCustomer",
    "format": "table"
  }
}

レスポンスの例（テーブル形式）：

Parameters for stored procedure: CreateNewCustomer

| Parameter | Type | Required | Direction | Default |
|-----------|------|----------|-----------|---------|
| CompanyName | nvarchar(40) | Yes | INPUT | - |
| ContactName | nvarchar(30) | No | INPUT | NULL |
| City | nvarchar(15) | No | INPUT | NULL |
| Country | nvarchar(15) | No | INPUT | USA |

Example usage:
```json
{
  "CompanyName": "Acme Corp",
  "ContactName": "John Doe",
  "City": "Seattle",
  "Country": "USA"
}

Example request (JSON Schema format):
```json
{
  "name": "get_stored_procedure_parameters",
  "parameters": {
    "procedureName": "CreateNewCustomer",
    "format": "json"
  }
}

レスポンスの例（JSON Schema 形式）：

{
  "procedureName": "CreateNewCustomer",
  "description": "Parameter schema for stored procedure CreateNewCustomer",
  "parameters": {
    "type": "object",
    "properties": {
      "CompanyName": {
        "type": "string",
        "maxLength": 40,
        "sqlType": "nvarchar(40)",
        "sqlParameter": "@CompanyName",
        "position": 1,
        "isOutput": false,
        "description": "Parameter @CompanyName of type nvarchar(40)"
      },
      "ContactName": {
        "type": "string",
        "maxLength": 30,
        "sqlType": "nvarchar(30)",
        "sqlParameter": "@ContactName",
        "position": 2,
        "isOutput": false,
        "hasDefault": true,
        "defaultValue": null,
        "description": "Parameter @ContactName of type nvarchar(30)"
      },
      "Country": {
        "type": "string",
        "maxLength": 15,
        "sqlType": "nvarchar(15)",
        "sqlParameter": "@Country",
        "position": 4,
        "isOutput": false,
        "hasDefault": true,
        "defaultValue": "USA",
        "description": "Parameter @Country of type nvarchar(15)"
      }
    },
    "required": ["CompanyName"],
    "additionalProperties": false
  },
  "returnValue": {
    "type": "integer",
    "sqlType": "int",
    "description": "Return code (0 for success)"
  }
}

execute_stored_procedure

パラメーターの型を自動変換してストアドプロシージャを実行します。

パラメーター：

• procedureName（必須）：ストアドプロシージャの名前。
• parameters（必須）：パラメーター値を含む JSON 文字列。
• timeoutSeconds（任意）：コマンドのタイムアウト秒数。既定のタイムアウトを上書きします。
• includeIoStats（任意）：テーブルごとの IO 統計を含めます。既定値は false です。
• includeExecutionPlan（任意）：実際の XML 実行プランを含めます。既定値は false です。
• maxCellOutputLength（任意）：セルごとに表示する最大文字数。この値を超える文字列は ... で省略されます。省略を無効にするには 0 を設定します。指定しない場合は、サーバーの既定値（MaxCellOutputLength、既定値は 40）が使用されます。

リクエストの例：

{
  "name": "execute_stored_procedure",
  "parameters": {
    "procedureName": "CreateNewCustomer",
    "parameters": "{\"CompanyName\": \"Acme Corp\", \"ContactName\": \"John Doe\", \"City\": \"Seattle\"}"
  }
}

機能：

• ストアドプロシージャのメタデータに基づく JSON から SQL 型への自動変換
• @ParameterName 形式と ParameterName 形式の両方をサポート
• 大文字と小文字を区別しないパラメーター照合
• パラメーター検証を含む詳細なエラーメッセージ
• 出力パラメーターと戻り値をサポート

start_query

接続中のデータベースで SQL クエリをバックグラウンドで開始します。進行状況を確認するためのセッション ID を返します。長時間実行されるクエリに最適です。

パラメーター：

• query（必須）：実行する SQL クエリ
• timeoutSeconds（任意）：タイムアウト秒数。指定しない場合は、既定のタイムアウトが使用されます。
• includeIoStats（任意）：テーブルごとの IO 統計を含めます。既定値は false です。
• includeExecutionPlan（任意）：実際の XML 実行プランを含めます。既定値は false です。

リクエストの例：

{
  "name": "start_query",
  "parameters": {
    "query": "SELECT * FROM LargeTable WHERE ProcessingDate >= '2024-01-01'",
    "timeoutSeconds": 600
  }
}

レスポンスの例：

{
  "sessionId": 12345,
  "startTime": "2024-12-19 10:30:00 UTC",
  "query": "SELECT * FROM LargeTable WHERE ProcessingDate >= '2024-01-01'",
  "databaseName": "connected database",
  "timeoutSeconds": 600,
  "status": "running",
  "message": "Query started successfully. Use get_session_status to check progress."
}

start_stored_procedure

ストアドプロシージャの実行をバックグラウンドで開始します。進行状況を確認するためのセッション ID を返します。実行時間の長いプロシージャに最適です。

パラメーター：

• procedureName（必須）：実行するストアドプロシージャの名前
• parameters（任意）：ストアドプロシージャのパラメーターを含む JSON オブジェクト（デフォルト：「{}」）
• timeoutSeconds（任意）：タイムアウト時間（秒）。指定しない場合は、デフォルトのタイムアウトが使用されます
• includeIoStats（任意）：テーブルごとの IO 統計を含めます。デフォルトは false です。
• includeExecutionPlan（任意）：実際の XML 実行プランを含めます。デフォルトは false です。

リクエスト例：

{
  "name": "start_stored_procedure",
  "parameters": {
    "procedureName": "GenerateMonthlyReport",
    "parameters": "{\"Month\": 12, \"Year\": 2024, \"IncludeDetails\": true}",
    "timeoutSeconds": 1200
  }
}

レスポンス例：

{
  "sessionId": 12346,
  "startTime": "2024-12-19 10:35:00 UTC",
  "procedureName": "GenerateMonthlyReport",
  "databaseName": "connected database",
  "parameters": {"Month": 12, "Year": 2024, "IncludeDetails": true},
  "timeoutSeconds": 1200,
  "status": "running",
  "message": "Stored procedure started successfully. Use get_session_status to check progress."
}

サーバーモードのツール

接続文字列で特定のデータベースを指定せずに接続すると、次の追加ツールが利用できます。

list_databases

SQL Server インスタンス上のすべてのデータベースを一覧表示します。

リクエスト例：

{
  "name": "list_databases",
  "parameters": {}
}

レスポンス例：

Available Databases:

Name       | State  | Size (MB) | Owner     | Compatibility
---------- | ------ | --------- | --------- | -------------
master     | ONLINE | 10.25     | sa        | 160
tempdb     | ONLINE | 25.50     | sa        | 160
model      | ONLINE | 8.00      | sa        | 160
msdb       | ONLINE | 15.75     | sa        | 160
Northwind  | ONLINE | 45.25     | sa        | 160

execute_query_in_database

特定のデータベースで SQL クエリを実行します。

パラメーター：

• databaseName（必須）：クエリを実行するデータベースの名前。
• query（必須）：実行する SQL クエリ。
• timeoutSeconds（任意）：コマンドのタイムアウト時間（秒）。デフォルトのタイムアウトを上書きします。
• includeIoStats（任意）：テーブルごとの IO 統計を含めます。デフォルトは false です。
• includeExecutionPlan（任意）：実際の XML 実行プランを含めます。デフォルトは false です。
• maxCellOutputLength（任意）：セルごとに表示する最大文字数。この値を超える文字列は ... で切り詰められます。切り詰めを無効にするには 0 を設定します。指定しない場合は、サーバーのデフォルト（MaxCellOutputLength、デフォルトは 40）が使用されます。

リクエスト例：

{
  "name": "execute_query_in_database",
  "parameters": {
    "databaseName": "Northwind",
    "query": "SELECT TOP 5 * FROM Customers"
  }
}

list_tables_in_database

特定のデータベース内のすべてのテーブルを一覧表示します。

パラメーター：

• databaseName（必須）：テーブルを一覧表示するデータベースの名前。

リクエスト例：

{
  "name": "list_tables_in_database",
  "parameters": {
    "databaseName": "Northwind"
  }
}

get_table_schema_in_database

特定のデータベースからテーブルのスキーマを取得します。

パラメーター：

• databaseName（必須）：テーブルを含むデータベースの名前。
• tableName（必須）：スキーマ情報を取得するテーブルの名前。

リクエスト例：

{
  "name": "get_table_schema_in_database",
  "parameters": {
    "databaseName": "Northwind",
    "tableName": "Customers"
  }
}

list_stored_procedures_in_database

特定のデータベース内のすべてのストアドプロシージャを一覧表示します。

パラメーター：

• databaseName（必須）：ストアドプロシージャを一覧表示するデータベースの名前。

リクエスト例：

{
  "name": "list_stored_procedures_in_database",
  "parameters": {
    "databaseName": "Northwind"
  }
}

get_stored_procedure_definition_in_database

特定のデータベースからストアドプロシージャの SQL 定義を取得します。

パラメーター：

• databaseName（必須）：ストアドプロシージャを含むデータベースの名前。
• procedureName（必須）：ストアドプロシージャの名前。

リクエスト例：

{
  "name": "get_stored_procedure_definition_in_database",
  "parameters": {
    "databaseName": "Northwind",
    "procedureName": "GetCustomerOrders"
  }
}

get_stored_procedure_parameters (Server Mode)

任意のデータベースからストアドプロシージャのパラメーター情報を取得します。

パラメーター：

• procedureName（必須）：ストアドプロシージャの名前。
• databaseName（任意）：ストアドプロシージャを含むデータベースの名前。
• format（任意）：出力形式。「table」（デフォルト）または「json」。

リクエスト例：

{
  "name": "get_stored_procedure_parameters",
  "parameters": {
    "procedureName": "CreateNewCustomer",
    "databaseName": "Northwind",
    "format": "json"
  }
}

execute_stored_procedure_in_database

特定のデータベースで、パラメーターの型を自動変換してストアドプロシージャを実行します。

パラメーター：

• databaseName（必須）：ストアドプロシージャが含まれるデータベースの名前です。
• procedureName（必須）：ストアドプロシージャの名前です。
• parameters（必須）：パラメーター値を含む JSON 文字列です。
• timeoutSeconds（任意）：コマンドのタイムアウト時間（秒）です。デフォルトのタイムアウト時間を上書きします。
• includeIoStats（任意）：テーブルごとの IO 統計を含めます。デフォルトは false です。
• includeExecutionPlan（任意）：実際の XML 実行プランを含めます。デフォルトは false です。
• maxCellOutputLength（任意）：セルごとに表示する最大文字数です。この値を超える文字列は ... で切り詰められます。切り詰めを無効にするには、0 を設定します。指定しない場合は、サーバーのデフォルト（MaxCellOutputLength、デフォルトは 40）が使用されます。

リクエストの例：

{
  "name": "execute_stored_procedure_in_database",
  "parameters": {
    "databaseName": "Northwind",
    "procedureName": "CreateNewCustomer",
    "parameters": "{\"CompanyName\": \"Acme Corp\", \"ContactName\": \"John Doe\"}"
  }
}

start_query_in_database

特定のデータベースで SQL クエリをバックグラウンドで開始します。進行状況を確認するためのセッション ID が返されます。長時間実行されるクエリに最適です（サーバーモード）。

パラメーター：

• databaseName（必須）：クエリを実行するデータベースの名前
• query（必須）：実行する SQL クエリ
• timeoutSeconds（任意）：タイムアウト時間（秒）。指定しない場合は、デフォルトのタイムアウト時間が使用されます。
• includeIoStats（任意）：テーブルごとの IO 統計を含めます。デフォルトは false です。
• includeExecutionPlan（任意）：実際の XML 実行プランを含めます。デフォルトは false です。

リクエストの例：

{
  "name": "start_query_in_database",
  "parameters": {
    "databaseName": "DataWarehouse",
    "query": "EXEC sp_refreshview 'vw_SalesSummary'; SELECT * FROM vw_SalesSummary",
    "timeoutSeconds": 900
  }
}

レスポンスの例：

{
  "sessionId": 12347,
  "startTime": "2024-12-19 10:40:00 UTC",
  "query": "EXEC sp_refreshview 'vw_SalesSummary'; SELECT * FROM vw_SalesSummary",
  "databaseName": "DataWarehouse",
  "timeoutSeconds": 900,
  "status": "running",
  "message": "Query started successfully. Use get_session_status to check progress."
}

start_stored_procedure_in_database

特定のデータベースでストアドプロシージャの実行をバックグラウンドで開始します。進行状況を確認するためのセッション ID が返されます。長時間実行されるストアドプロシージャに最適です（サーバーモード）。

パラメーター：

• databaseName（必須）：ストアドプロシージャが含まれるデータベースの名前
• procedureName（必須）：実行するストアドプロシージャの名前
• parameters（任意）：ストアドプロシージャのパラメーターを含む JSON オブジェクト（デフォルト："{}"）
• timeoutSeconds（任意）：タイムアウト時間（秒）。指定しない場合は、デフォルトのタイムアウト時間が使用されます。
• includeIoStats（任意）：テーブルごとの IO 統計を含めます。デフォルトは false です。
• includeExecutionPlan（任意）：実際の XML 実行プランを含めます。デフォルトは false です。

リクエストの例：

{
  "name": "start_stored_procedure_in_database",
  "parameters": {
    "databaseName": "Analytics",
    "procedureName": "sp_BuildDataMart",
    "parameters": "{\"StartDate\": \"2024-01-01\", \"EndDate\": \"2024-12-31\", \"RebuildIndexes\": true}",
    "timeoutSeconds": 3600
  }
}

レスポンスの例：

{
  "sessionId": 12348,
  "startTime": "2024-12-19 10:45:00 UTC",
  "procedureName": "sp_BuildDataMart",
  "databaseName": "Analytics",
  "parameters": {"StartDate": "2024-01-01", "EndDate": "2024-12-31", "RebuildIndexes": true},
  "timeoutSeconds": 3600,
  "status": "running",
  "message": "Stored procedure started successfully. Use get_session_status to check progress."
}

設定

ツールのセキュリティ設定

サーバーでは、危険性のある操作を利用可能にするかどうかを細かく制御できます。

クエリ実行のセキュリティ

セキュリティ上の理由から、SQL クエリ実行ツールはデフォルトで無効になっています。これらのツールを有効にするには、設定 EnableExecuteQuery を true にします。

ストアドプロシージャ実行のセキュリティ

セキュリティ上の理由から、ストアドプロシージャ実行ツールはデフォルトで無効になっています。これらのツールを有効にするには、設定 EnableExecuteStoredProcedure を true にします。

セッションベース実行のセキュリティ

セキュリティ上の理由から、セッションベースのクエリ実行ツールはデフォルトで無効になっています。これらのツールを有効にするには、設定 EnableStartQuery を true にします。

セキュリティ上の理由から、セッションベースのストアドプロシージャ実行ツールはデフォルトで無効になっています。これらのツールを有効にするには、設定 EnableStartStoredProcedure を true にします。

これらは、次のいずれかの方法で設定できます。

1. appsettings.json ファイルで設定する：

{
  "DatabaseConfiguration": {
    "EnableExecuteQuery": true,
    "EnableExecuteStoredProcedure": true,
    "EnableStartQuery": true,
    "EnableStartStoredProcedure": true
  }
}

2. コンテナーの実行時に環境変数として設定する：

docker run \
  -e "DatabaseConfiguration__EnableExecuteQuery=true" \
  -e "DatabaseConfiguration__EnableExecuteStoredProcedure=true" \
  -e "DatabaseConfiguration__EnableStartQuery=true" \
  -e "DatabaseConfiguration__EnableStartStoredProcedure=true" \
  -e "MSSQL_CONNECTIONSTRING=Server=your_server;..." \
  aadversteeg/mssqlclient-mcp-server:latest

3. Claude Desktop の設定で指定する：

"mssql": {
  "command": "dotnet",
  "args": [
    "YOUR_PATH_TO_DLL\\Core.Infrastructure.McpServer.dll"
  ],
  "env": {
    "MSSQL_CONNECTIONSTRING": "Server=your_server;...",
    "DatabaseConfiguration__EnableExecuteQuery": "true",
    "DatabaseConfiguration__EnableExecuteStoredProcedure": "true",
    "DatabaseConfiguration__EnableStartQuery": "true",
    "DatabaseConfiguration__EnableStartStoredProcedure": "true"
  }
}

これらの設定が false（デフォルト）の場合、該当する実行ツールは登録されず、クライアントから利用できません。これにより、読み取り専用の操作のみを許可したい場合に、セキュリティをさらに強化できます。

タイムアウトの設定

SQL Server MCP Client では、さまざまなワークロード要件に対応できるよう、複数のレベルで包括的なタイムアウト設定を行えます。

デフォルトのタイムアウト設定

appsettings.json でデフォルトのタイムアウトを設定します。

{
  "DatabaseConfiguration": {
    "DefaultCommandTimeoutSeconds": 30,
    "ConnectionTimeoutSeconds": 15,
    "MaxConcurrentSessions": 10,
    "SessionCleanupIntervalMinutes": 60,
    "TotalToolCallTimeoutSeconds": 120,
    "MaxCellOutputLength": 40
  }
}

タイムアウト設定：

• DefaultCommandTimeoutSeconds：SQL コマンドの実行に対するデフォルトのタイムアウト（デフォルト：30 秒）
• ConnectionTimeoutSeconds：SQL 接続の確立に対するタイムアウト（デフォルト：15 秒）
• MaxConcurrentSessions：同時に実行できるクエリセッションの最大数（デフォルト：10）
• SessionCleanupIntervalMinutes：完了したセッションをクリーンアップする間隔（デフォルト：60 分）
• TotalToolCallTimeoutSeconds：ツール呼び出しの完了に許可される最大時間（デフォルト：120 秒。無効にするには null を設定）
• MaxCellOutputLength：クエリ結果でセルごとに表示する最大文字数。この値を超えると ... で切り詰められます。切り詰めを無効にするには 0 を設定します（デフォルト：40）

環境変数でも設定できます。

# Docker example
docker run \
  -e "DatabaseConfiguration__DefaultCommandTimeoutSeconds=60" \
  -e "DatabaseConfiguration__ConnectionTimeoutSeconds=30" \
  -e "DatabaseConfiguration__TotalToolCallTimeoutSeconds=180" \
  -e "MSSQL_CONNECTIONSTRING=Server=your_server;..." \
  aadversteeg/mssqlclient-mcp-server:latest

# Claude Desktop configuration
"mssql": {
  "command": "docker",
  "args": ["run", "--rm", "-i",
    "-e", "DatabaseConfiguration__DefaultCommandTimeoutSeconds=60",
    "-e", "DatabaseConfiguration__ConnectionTimeoutSeconds=30",
    "-e", "DatabaseConfiguration__TotalToolCallTimeoutSeconds=180",
    "-e", "MSSQL_CONNECTIONSTRING=Server=your_server;...",
    "aadversteeg/mssqlclient-mcp-server:latest"
  ]
}

ツール呼び出しのタイムアウト管理

TotalToolCallTimeoutSeconds 設定は、ツールが無期限に実行されるのを防ぐ安全対策です。

仕組み：

• 単一のツール呼び出しの完了に、最大時間を設定します
• 最大時間を超えると、明確なタイムアウトエラーメッセージを表示して操作をキャンセルします
• 操作のハングを防ぎ、応答性を確保します
• 操作ごとのタイムアウトと併用することで、きめ細かな制御が可能です

設定時の考慮事項：

• MCP クライアントの制限：ほとんどの MCP クライアント（Claude Desktop など）の接続タイムアウトは 2～5 分です
• ベストプラクティス：最適なユーザーエクスペリエンスのため、TotalToolCallTimeoutSeconds はクライアントのタイムアウトより短く設定します（通常は 90～120 秒）
• 時間のかかる操作：より長い時間が必要な操作には、セッションベースのツール（start_query、start_stored_procedure）を使用します
• 必要に応じて無効化：合計タイムアウト制限を無効にするには null を設定します

設定例：

{
  "TotalToolCallTimeoutSeconds": 90,  // 1.5 minutes - good for most operations
  "DefaultCommandTimeoutSeconds": 30  // Default timeout for individual SQL commands
}

この設定により、次のようになります。

• ツール呼び出しの合計実行時間は 90 秒以内です
• 個々の SQL コマンドのデフォルトのタイムアウトは 30 秒です
• 時間のかかる操作には、代わりにセッションベースのツールを使用します

実行時のタイムアウト管理

サーバーには、タイムアウトを動的に管理するツールが用意されています。

get_command_timeout

現在のタイムアウト設定を返します。

リクエスト例：

{
  "name": "get_command_timeout",
  "parameters": {}
}

レスポンス例：

{
  "defaultCommandTimeoutSeconds": 30,
  "connectionTimeoutSeconds": 15,
  "maxConcurrentSessions": 10,
  "sessionCleanupIntervalMinutes": 60,
  "totalToolCallTimeoutSeconds": 120,
  "timestamp": "2024-12-19 10:30:45 UTC"
}

set_command_timeout

新しい操作すべてに適用されるデフォルトのコマンドタイムアウトを更新します。既存の操作には、元のタイムアウトが引き続き適用されます。

パラメーター：

• timeoutSeconds（必須）：新しいタイムアウト（秒、1～3600）

リクエスト例：

{
  "name": "set_command_timeout",
  "parameters": {
    "timeoutSeconds": 120
  }
}

レスポンス例：

{
  "message": "Default command timeout updated successfully",
  "oldTimeoutSeconds": 30,
  "newTimeoutSeconds": 120,
  "note": "This change only affects new operations. Existing sessions will continue with their original timeout settings.",
  "timestamp": "2024-12-19 10:31:00 UTC"
}

操作ごとのタイムアウト

ほとんどのデータベース操作では、オプションの timeoutSeconds パラメーターを使用できます。このパラメーターを指定すると、その操作に限りデフォルトのタイムアウトが上書きされます。

// Long-running query with 5-minute timeout
{
  "name": "execute_query",
  "parameters": {
    "query": "SELECT * FROM LargeTable WITH (NOLOCK)",
    "timeoutSeconds": 300
  }
}

// Complex stored procedure with 10-minute timeout
{
  "name": "execute_stored_procedure",
  "parameters": {
    "procedureName": "GenerateMonthlyReport",
    "parameters": "{}",
    "timeoutSeconds": 600
  }
}

// Quick table list with 10-second timeout
{
  "name": "list_tables",
  "parameters": {
    "timeoutSeconds": 10
  }
}

操作ごとのタイムアウトに対応するツール：

• すべてのクエリ実行ツール（execute_query、execute_query_in_database）
• すべてのストアドプロシージャツール（execute_stored_procedure、execute_stored_procedure_in_database、get_stored_procedure_parameters）
• すべてのスキーマ検出ツール（list_tables、get_table_schema、list_stored_procedures）
• セッション管理ツール（start_query、start_stored_procedure、start_query_in_database、start_stored_procedure_in_database）

ベストプラクティス

1. デフォルト設定：一般的なワークロードに基づいて、appsettings.json に適切なデフォルト値を設定します
2. 合計タイムアウト：MCP クライアントとの互換性を最適化するため、TotalToolCallTimeoutSeconds を 90～120 秒に設定します
3. 長時間の操作：実行時間が長いことがわかっているクエリやプロシージャには、操作ごとのタイムアウトを使用します
4. 動的な調整：日中にさまざまなワークロードを扱う場合は、set_command_timeout を使用します
5. モニタリング：重要な操作を実行する前に、get_command_timeout を使用して現在の設定を確認します
6. バックグラウンド操作：タイムアウト制限を超える操作には、セッションベースのツールを使用します：
   • 長時間実行されるクエリには、start_query / start_query_in_database を使用します
   • 長時間実行されるプロシージャには、start_stored_procedure / start_stored_procedure_in_database を使用します
   • get_session_status で進行状況を監視します
   • get_session_results で結果を取得します
   • 必要に応じて、stop_session でキャンセルします
   • これらのツールは TotalToolCallTimeoutSeconds の制限を回避し、バックグラウンドで実行されます

タイムアウトの制限

• コマンドタイムアウト：1～3600 秒（最大 1 時間）
• 接続タイムアウト：起動時のみ設定可能（実行時の変更不可）
• 操作ごとの上書き：デフォルト設定より常に優先されます

データベース接続文字列

データベースへの接続には、SQL Server の接続文字列が必要です。この接続文字列には、サーバー情報、認証情報、および必要な接続オプションを含めてください。

MSSQL_CONNECTIONSTRING 環境変数を使用して接続文字列を設定できます：

# Database Mode with all execution types enabled
docker run \
  -e "DatabaseConfiguration__EnableExecuteQuery=true" \
  -e "DatabaseConfiguration__EnableExecuteStoredProcedure=true" \
  -e "DatabaseConfiguration__EnableStartQuery=true" \
  -e "DatabaseConfiguration__EnableStartStoredProcedure=true" \
  -e "MSSQL_CONNECTIONSTRING=Server=your_server;Database=your_db;User Id=your_user;Password=your_password;TrustServerCertificate=True;" \
  aadversteeg/mssqlclient-mcp-server:latest

# Server Mode with all execution types enabled
docker run \
  -e "DatabaseConfiguration__EnableExecuteQuery=true" \
  -e "DatabaseConfiguration__EnableExecuteStoredProcedure=true" \
  -e "DatabaseConfiguration__EnableStartQuery=true" \
  -e "DatabaseConfiguration__EnableStartStoredProcedure=true" \
  -e "MSSQL_CONNECTIONSTRING=Server=your_server;User Id=your_user;Password=your_password;TrustServerCertificate=True;" \
  aadversteeg/mssqlclient-mcp-server:latest

サーバーモードとデータベースモード

MCP サーバーは、接続文字列に基づいてモードを自動的に検出します：

• サーバーモード：接続文字列でデータベースが指定されていない場合（Database= または Initial Catalog= パラメーターがない場合）
• データベースモード：接続文字列で特定のデータベースが指定されている場合

接続文字列の例：

# Database Mode - Connects to specific database
Server=database.example.com;Database=Northwind;User Id=sa;Password=YourPassword;TrustServerCertificate=True;

# Server Mode - No specific database
Server=database.example.com;User Id=sa;Password=YourPassword;TrustServerCertificate=True;

# Database Mode with Windows Authentication
Server=database.example.com;Database=Northwind;Integrated Security=SSPI;TrustServerCertificate=True;

# Server Mode with specific port
Server=database.example.com,1433;User Id=sa;Password=YourPassword;TrustServerCertificate=True;

接続文字列が指定されていない場合、ツールの使用時にサーバーはエラーメッセージを返します。

注記： Docker コンテナーで実行する場合、統合セキュリティ（Windows 認証）はサポートされていません。代わりに SQL Server 認証を使用してください。

Docker の使用

.NET 10 SDK は不要です。

"mssql": {
  "command": "docker",
  "args": [
    "run",
    "--rm",
    "-i",
    "-e", "MSSQL_CONNECTIONSTRING=Server=your_server;Database=your_db;User Id=your_user;Password=your_password;TrustServerCertificate=True;",
    "-e", "DatabaseConfiguration__EnableExecuteQuery=true",
    "-e", "DatabaseConfiguration__EnableExecuteStoredProcedure=true",
    "-e", "DatabaseConfiguration__EnableStartQuery=true",
    "-e", "DatabaseConfiguration__EnableStartStoredProcedure=true",
    "aadversteeg/mssqlclient-mcp-server:latest"
  ]
}

Windows でローカル SQL Server を使用する場合の注意： Windows 上の Docker Desktop からローカルの SQL Server インスタンスに接続する場合は、SQL Server Configuration Manager（SQL Server Network Configuration → Protocols for MSSQLSERVER → TCP/IP）で TCP/IP が有効になっていること、および SQL Server がポート 1433 をリッスンするように設定されていること（TCP/IP Properties → IP Addresses → IPAll → TCP Port: 1433）を確認してください。これらの変更を行った後、SQL Server サービスを再起動してください。

アーキテクチャ

インターフェース設計

サーバーは、関心事を明確に分離するため、3 層のインターフェースアーキテクチャを実装しています：

1. IDatabaseService（コア層）

   • タイムアウトコンテキストを伴わない低レベルのデータベース操作
   • SQL Server との直接通信
   • 接続とコマンドの管理

2. IServerDatabase（サーバーモード層）

   • データベースをまたぐサーバー全体の操作
   • タイムアウトコンテキスト管理を含みます
   • データベースの切り替えとデータベース間クエリ

3. IDatabaseContext（データベースモード層）

   • データベースをスコープとする操作
   • 単一データベースのシナリオ向けに簡素化されたインターフェース
   • タイムアウトコンテキスト管理を含みます

タイムアウト管理

サーバーは、統一されたタイムアウト管理システムを使用します：

• ToolCallTimeoutContext：すべての高レベルインターフェースで使用される null 許容パラメーター
• 簡素化された API：タイムアウトコンテキストを任意で指定できる単一のメソッドシグネチャ
• すっきりとした設計：メソッドのオーバーロードを使わず、null 許容パラメーターで柔軟性を確保します
• 一貫したエラー処理：標準化されたエラー形式："Error: SQL error while {operation}: {message}"

型システム

このサーバーには、保存されたプロシージャのパラメーターのメタデータに基づいて、JSON 値を適切な SQL Server 型に変換する高度な型マッピングシステムが含まれています。

• 自動型検出：SQL Server の sys.parameters メタデータを信頼できる情報源として使用します
• 幅広い型のサポート：varchar、nvarchar、int、decimal、datetime、uniqueidentifier など、主要な SQL Server データ型すべてに対応します
• 検証：型の不一致や制約違反について、詳細なエラーメッセージを表示します
• デフォルト値：デフォルト値を持つパラメーターと省略可能なパラメーターに対応します

パラメーターの処理

• 大文字と小文字を区別しない：パラメーター名は大文字と小文字を区別せずに照合されます
• 柔軟な名前指定：@ParameterName と ParameterName の両方の形式に対応します
• 正規化：パラメーター名の自動正規化と検証を行います
• JSON Schema：パラメーター検証に対応した JSON Schema 出力を生成します

セキュリティモデル

このサーバーは、多層的なセキュリティ対策を実装しています。

1. ツールレベルのセキュリティ：設定を通じて個々のツールを有効または無効にできます
2. パラメーター検証：すべての入力を SQL Server のメタデータに照らして検証します
3. SQL インジェクション対策：すべての処理でパラメーター化クエリを使用します
4. 接続セキュリティ：すべての SQL Server 認証方式に対応します

技術スタック

• フレームワーク：.NET 10.0 と C# 14
• 言語機能：Nullable reference types、async/await、records
• データベースアクセス：Microsoft.Data.SqlClient
• MCP SDK：Model Context Protocol C# SDK
• テスト：包括的なユニットテストのための xUnit と Moq
• コンテナー化：イメージを最適化するマルチステージ Docker ビルド

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については、LICENSE ファイルをご覧ください。