SQL Server MCP

数十台のインスタンスを管理する人のための SQL Server MCP

MCP エントリは 1 つで、管理するすべての SQL Server に接続できます。接続情報は単一の connections.json にまとめられ、クライアントまたは環境ごとにグループ化できます。AI エージェントを再起動せずにホットリロードでき、実行プラン、インデックス監査、ストアドプロシージャの分析にも対応しています。

単一の localhost データベースを使ったデモではなく、DBA とコンサルタント向けに作られています。

インストール

AI エージェントの MCP 設定に次の内容を追加します。

{
  "mcpServers": {
    "sqlserver": {
      "command": "npx",
      "args": ["-y", "@cevelas/mcp-sqlserver"]
    }
  }
}

次に、接続ファイルを作成してエージェントを再起動します。

npx -y @cevelas/mcp-sqlserver --init

コメント付きのテンプレートから ~/.mcp-sqlserver/connections.json が作成されます。ファイルを編集し、エージェントに 「すべての SQL Server 接続を一覧表示して」 と尋ねてください。

Node.js 22 以降が必要です。

各エージェントが MCP 設定を保存する場所

エージェント	設定ファイル
Claude Desktop（Windows）	%APPDATA%\Claude\claude_desktop_config.json
Claude Desktop（macOS）	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Code	claude mcp add sqlserver -- npx -y @cevelas/mcp-sqlserver
VS Code / Copilot	.vscode/mcp.json
Cursor	~/.cursor/mcp.json

MCP 互換のエージェントならどれでも動作します。ChatGPT、Gemini、Copilot、Cline、Zed などは、すべて同じ command / args の組み合わせを使用します。

この MCP サーバーを選ぶ理由

多くの SQL Server MCP サーバーは、単一の接続文字列を使います。データベースが 1 つなら問題ありません。しかし、8 つのクライアントにまたがる 30 台のサーバーを管理する場合、各インスタンスをエージェント設定に個別に登録し、それぞれの認証情報を管理し、変更のたびに再起動する必要があるため、うまくいきません。

	単一 DSN のサーバー	このサーバー
MCP エントリあたりのインスタンス数	1	すべて
クライアントまたは環境ごとの整理	—	connectionGroup
接続の追加や変更	エージェント設定を編集して再起動	ファイルを編集して reload_connections
応答したサーバーの確認	推測する	すべての応答の metadata に記載
SELECT 以外の機能	—	実行プラン、インデックス構成、ストアドプロシージャのソース
読み取り専用の安全策	—	接続ごとに "readOnly": true

接続

{
  "connections": [
    {
      "name": "acme-prod",
      "connectionGroup": "Acme Corp",
      "description": "Production - head office",
      "server": "192.168.1.10\\SQLEXPRESS",
      "database": "AcmeDB_Prod",
      "user": "app_reader",
      "password": "${env:ACME_PROD_PASSWORD}",
      "port": 1433,
      "encrypt": true,
      "trustServerCertificate": false,
      "readOnly": true
    }
  ]
}

フィールド	必須	備考
name	はい	一意の名前です。エージェントに伝える名前です
server	はい	ホスト名、IP、または host\instance
connectionGroup	いいえ	クライアント、プロジェクト、または環境です。一覧をグループ化します
description	いいえ	list_connections とすべての応答に表示されます
database	いいえ	ログインの既定データベースが使用されます
user、password	いいえ	ドメイン認証または Entra ID 認証では省略します
port	いいえ	既定値は 1433 です
encrypt、trustServerCertificate	いいえ	encrypt の既定値は true です
readOnly	いいえ	書き込みステートメントを拒否します。詳細は以下を参照してください

ここに指定したその他の項目はすべて mssql にそのまま渡されるため、requestTimeout、connectionTimeout、pool、authentication、ネストされた options オブジェクトも使用できます。

パスワードをファイルに含めない

どの文字列でも環境変数を参照できます。

"password": "${env:ACME_PROD_PASSWORD}"

設定していない変数を参照する接続は無効になり、list_connections には接続名と不足している変数の両方が表示されます。リテラルをそのまま残すと、接続時までエラーが先送りされ、Login failed for user と表示されるだけで、原因は何も分かりません。

ファイルを使わず、設定全体をエージェントの設定に渡すこともできます。これにより、他の MCP シークレットと一緒に認証情報を一元管理できます。

{
  "mcpServers": {
    "sqlserver": {
      "command": "npx",
      "args": ["-y", "@cevelas/mcp-sqlserver"],
      "env": {
        "MSSQL_MCP_CONNECTIONS_JSON": "{\"connections\":[{\"name\":\"prod\",\"server\":\"10.0.0.1\",\"database\":\"App\",\"user\":\"reader\",\"password\":\"...\"}]}"
      }
    }
  }
}

ファイルの検索場所

次の順に検索し、最初に見つかったものが使われます。

1. --connections <path>
2. $MSSQL_MCP_CONNECTIONS — パス
3. $MSSQL_MCP_CONNECTIONS_JSON — JSON 自体をインラインで指定
4. 作業ディレクトリ内の ./connections.json
5. ~/.mcp-sqlserver/connections.json
6. インストール済みパッケージと同じ場所にある connections.json

1 または 2 で明示的に指定したパスが存在しない場合はエラーになります。サーバーが別のファイルに黙って切り替えて、誤ったデータベースに接続することはありません。

すべての接続を一度に確認する

npx -y @cevelas/mcp-sqlserver --check

すべてのエントリに並列で接続し、SELECT 1 を実行して、失敗した接続とその理由を一覧表示します。いずれかが失敗するとゼロ以外の終了コードを返すため、スケジュールされたタスクでも使えます。パスワードのローテーション後や、エージェントを疑う前に確認するのに便利です。

Windows ドメイン認証と Entra ID 認証

同梱の tedious ドライバーは、NTLM と Entra ID（Azure AD）系の認証に対応しています。NTLM では domain を追加します。

{
  "name": "warehouse",
  "server": "dwh.corp.local",
  "database": "DWH",
  "domain": "CORP",
  "user": "svc_analytics",
  "password": "${env:DWH_PASSWORD}"
}

{
  "name": "azure-sql",
  "server": "myserver.database.windows.net",
  "database": "reporting",
  "encrypt": true,
  "authentication": {
    "type": "azure-active-directory-password",
    "options": { "userName": "${env:AZURE_USER}", "password": "${env:AZURE_PASSWORD}" }
  }
}

パスワードを使わない完全な統合認証（信頼された接続）には、ネイティブの msnodesqlv8 ドライバーが必要です。ビルドツールチェーンのないマシンでワンライナーによるインストールができなくなるため、このドライバーは同梱されていません。明示的なサービスアカウントを使った NTLM が、サポートされている方法です。

ツール

ツール	引数	機能
list_connections	—	接続をすべてグループごとに一覧表示
reload_connections	—	ファイルを再読み込みし、開いているプールを破棄
query	connection、sql、maxRows?、format?	クエリを実行
get_schema	connection、table?	列、型、NULL 許容性、デフォルト値
get_indexes	connection、table	インデックス、型、キー列、含まれる列
get_execution_plan	connection、sql	SHOWPLAN_XML — クエリを実行せずに実行計画を取得
get_stored_procedure	connection、name	ストアドプロシージャのソース

すべての応答には、どの接続から取得したかが含まれます。

{
  "metadata": {
    "connection": "acme-prod",
    "connectionGroup": "Acme Corp",
    "description": "Production - head office",
    "server": "192.168.1.10\\SQLEXPRESS",
    "database": "AcmeDB_Prod"
  },
  "data": [ ... ]
}

30 個の接続を扱う場合、この行があれば、意図したクライアントからの回答かどうかが分かります。

コンテキストウィンドウに収まるクエリ結果

SELECT * FROM Orders を実行するエージェントに、400 万行は必要ありません。コンテキストウィンドウにも必要ありません。

• 行数の上限。 query は、すべての結果セットを合わせて最大 1000 行を返します。maxRows で上限を変更できますが、最大 10000 行です。上限に達すると、クエリは後から切り詰められるのではなく、サーバー上でキャンセルされます。
• 切り詰められた結果では、その旨が最初に示されます。 レスポンスは "truncated": true と、さらに行があること、合計行数は不明であること、合計を取得する方法を示す注記で始まります。これは意図的に行より前に置かれています。10000 行のレスポンスは数百 KB に及び、長い出力を切り詰めるクライアントでは先頭部分が残るためです。エージェントは、上限に達した結果から「テーブルには 10000 行ある」と決して結論づけてはいけません。10000 を超える行数を要求してもエラーにはなりません。上限は 10000 に引き下げられ、行が除外された場合は、要求された行数が注記に示されます。
• format: "csv"。 JSON では、すべての行で列名が繰り返されます。csv の場合、レスポンスはメタデータを含む JSON のヘッダー行、空行、そして行データの順になります。NULL は空のセル、空文字列は "" となるため、両者を区別できます。
• サーバーメッセージ。 PRINT の出力と SET STATISTICS IO, TIME ON の結果は messages で返されるため、エージェントは推測ではなく、論理読み取り数と CPU 時間を確認できます。
• すべての結果セット。 複数の SELECT を含むバッチでは、すべての結果セットが recordsets で返されます。data には引き続き最初の結果セットが入ります。
• バイナリ列は、バイトごとに数値を並べた JSON 配列ではなく、16 進数（0x8f3a...）で返され、64 バイトを超える部分は切り詰められます。

rowCount は常に含まれます。truncated、messages、recordsets は、示す内容がある場合にのみ含まれます。レスポンスはコンパクトな JSON です。

これでできること

手作業では面倒な作業も、エージェントには一文で指示できます。

• 「このストアドプロシージャが遅いのはなぜ？」 — ソースには get_stored_procedure、実行プランには get_execution_plan、不足しているものには get_indexes を使います。
• 「acme-prod と acme-qa の Orders スキーマを比較して」 — 両方に get_schema を使い、エージェントが差分を確認します。
• 「このテーブルで、カバーリングに使われていないインデックスはどれ？」 — get_indexes と、確認したいクエリを使います。
• 「connections.json にクライアントを追加した」 — 再起動せずに reload_connections を使います。

読み取り専用接続

"readOnly": true

クエリがマシンから送信される前に、INSERT、UPDATE、DELETE、MERGE、DROP、TRUNCATE、ALTER、CREATE、GRANT、EXEC、BACKUP、DBCC、OPENQUERY、DISABLE／ENABLE などを拒否します。また、バッチの先頭が読み取りを行う文であることも必須です。T-SQL では EXEC を使わずにプロシージャを呼び出せるうえ、sp_rename 'dbo.Users','Users_old' にはブロック対象のキーワードが一切含まれないためです。先頭には SELECT、WITH、DECLARE、SET、IF などを指定できます。

文字列リテラル、コメント、角括弧で囲まれた識別子は無視されるため、WHERE note = 'please delete this'、SELECT [delete] FROM [Audit]、DECLARE @Create DATETIME はすべて許可されます。get_execution_plan は、SHOWPLAN_XML が何も実行せずにプランを返すため、引き続き使用できます。

明示的な false 以外はすべてガードが有効になります。手書きの "readOnly": "false" は、接続を暗黙に開放するのではなくロックダウンし、その旨が list_connections に表示されます。

これはガードレールであり、セキュリティ境界ではありません。 本番環境の行を「親切心で」修正しようとするエージェントを止めますが、書き込みを決意したユーザーは止められません。本当の保護策は、db_datareader のみが付与された SQL ログインです。

CREATE LOGIN mcp_reader WITH PASSWORD = '...';
CREATE USER mcp_reader FOR LOGIN mcp_reader;
ALTER ROLE db_datareader ADD MEMBER mcp_reader;
GRANT VIEW DEFINITION TO mcp_reader;   -- for get_stored_procedure
GRANT SHOWPLAN TO mcp_reader;          -- for get_execution_plan

両方を使用してください。

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

• connections.json には認証情報が含まれます。バージョン管理に含めないでください。付属の .gitignore で connections*.json は除外されます。
• パスワードを直接記述するのではなく、${env:VAR} を使用してください。
• 各接続には、必要最小限の権限を付与してください。sa は使用しないでください。
• ファイルのアクセス許可を制限してください。 Windows では icacls connections.json /inheritance:r /grant:r "%USERNAME%:F"、 それ以外では chmod 600 connections.json を実行します。
• query ツールは、エージェントが作成した SQL をそのまま実行します。それがこのツールの役割です。境界となるのはツールではなく、接続に付与した権限だと考えてください。

Web UI

web/connections.html は、JSON を手書きせずに connections.json を編集できるスタンドアロンページです。グループ間のドラッグ＆ドロップ、接続の複製、入力補完機能付きのグループ選択、Chrome と Edge の File System Access API を使った自動保存に対応しています。ビルド不要、依存関係なしで、使用は完全に任意です。詳しくは web/README.md をご覧ください。

Claude Desktop のワンクリックインストール

最新リリースから .mcpb バンドルをダウンロードし、Claude Desktop の拡張機能設定にドラッグします。拡張機能の設定で connections.json を指定するか、空欄のままにすると ~/.mcp-sqlserver/connections.json が使用されます。

2.x からのアップグレード

既存の connections.json は変更せずに使用できます。新しいフィールドはすべて任意で、ツールに渡す引数も同じです。知っておくべき点は 2 つあります。

• 3.0 より前は複数接続が正しく機能していませんでした。 サーバーは mssql のグローバル接続プールを使用していましたが、接続がすでに開いていると、渡された設定が無視されていました。そのため、実際には最初の接続以降、どの接続も最初の接続先のサーバーとデータベースを気付かないうちに再利用していました。セッション中に複数の接続からの結果を利用していた場合、想定した接続先から取得した結果ではなかった可能性があります。3.0 では接続ごとにプールを用意して修正しました。
• エージェントの設定で node C:\path\to\index.js を指定している場合も、引き続き動作します。ファイルの検索順序ではこのパスが最後に確認されるようになりましたが、変更は不要です。

開発

npm install
npm test                     # unit tests, no database needed
node .github/scripts/smoke.mjs   # packs, installs and speaks MCP to the tarball

実際のサーバーを使用する場合は、自分のファイルから接続名を指定します。

MSSQL_TEST_CONNECTION=local npm run test:integration

mssql ドライバーは注入されるため、単体テストではその境界だけをモックし、それ以外には実際のコードパスを使用します。test/contract.test.js ではツール名と引数を固定し、リファクタリングによって MCP のインターフェイスが誤って変更されないようにしています。

ライセンス

MIT — LICENSE をご覧ください。

作者

Christian Velasquez — @cvelasquez

Issue · 変更履歴 · スポンサー