MS SQL Server MCP Server

MS SQL Server MCP Server v3.0.0

🚀 Microsoft SQL Server 用のModel Context Protocol（MCP）サーバーです。Claude Desktop、Cursor、Windsurf、VS Code と互換性があります。

標準への準拠

• プロトコルの対象：MCP draft/latest spec
• トランスポート仕様：Transports
• セキュリティ：Security best practices
• SDK：@modelcontextprotocol/server / @modelcontextprotocol/client / @modelcontextprotocol/node v2（2.0.0）。2026-07-28 MCP spec を対象としています
• Node.js >= 20 が必要です

🚀 クイックスタート

1. インストール

npm install -g mssql-mcp

2. IDE の設定

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "mssql": {
      "command": "npx",
      "args": ["-y", "mssql-mcp@latest"],
      "env": {
        "DB_SERVER": "your-server.com",
        "DB_DATABASE": "your-database",
        "DB_USER": "your-username",
        "DB_PASSWORD": "your-password",
        "DB_ENCRYPT": "true",
        "DB_TRUST_SERVER_CERTIFICATE": "true"
      }
    }
  }
}

Cursor/Windsurf/VS Code（.vscode/mcp.json）：

{
  "servers": {
    "mssql": {
      "command": "npx",
      "args": ["-y", "mssql-mcp@latest"],
      "env": {
        "DB_SERVER": "your-server.com",
        "DB_DATABASE": "your-database",
        "DB_USER": "your-username",
        "DB_PASSWORD": "your-password",
        "DB_ENCRYPT": "true",
        "DB_TRUST_SERVER_CERTIFICATE": "true"
      }
    }
  }
}

HTTP トランスポート（リモート／ホスト環境）：

{
  "servers": {
    "mssql": {
      "type": "http",
      "url": "http://127.0.0.1:3001",
      "env": {}
    }
  }
}

実際のデータベース認証情報に置き換えてください。認証情報はサーバー環境からのみ読み込まれ、ツールのパラメーターとして渡されることはありません。

��️ ツール一覧

主要ツール（こちらを使用してください）

ツール	読み取り専用	説明
mssql_connect_database	いいえ	環境変数を使用して接続します。冪等です。
mssql_disconnect_database	いいえ	接続を閉じます。冪等です。
mssql_connection_status	✅	接続状態とプールのメトリクス
mssql_run_sql_query	⚠️ いいえ	任意の SQL を実行します。データを変更する可能性があります。
mssql_list_schema_objects	✅	ページネーションを使用してテーブル／ビュー／プロシージャ／関数を一覧表示します
mssql_describe_table_columns	✅	テーブルの列定義
mssql_read_table_rows	✅	射影と安全な WHERE 条件を使用したページネーション対応の行データ
mssql_execute_stored_procedure	⚠️ いいえ	ストアドプロシージャを実行します
mssql_list_databases	✅	インスタンス上のすべてのデータベースを一覧表示します

すべてのデータツールは response_format パラメーター（"json" | "markdown"、既定値は "json"）を受け付けます。人が読みやすい表形式の出力を得るには、"markdown" を使用してください。

非推奨のエイリアス（後方互換性のため引き続き登録されています）

これらは、サーバーが実際に登録する唯一のエイリアスツール名です（src/tools/*.ts）。 置き換え後のツールと同じように動作しますが、新しい連携ではドキュメントに記載されていません。 上記の主要ツール名を使用してください。

古い名前	代わりに使用
mssql_execute_query	mssql_run_sql_query
mssql_get_schema	mssql_list_schema_objects
mssql_describe_table	mssql_describe_table_columns
mssql_get_table_data	mssql_read_table_rows
mssql_execute_procedure	mssql_execute_stored_procedure

🚌 トランスポートモード

モード	使用する場面
stdio（既定）	ローカル IDE との連携（Claude Desktop、Cursor、VS Code）
http	リモート／ホスト環境へのデプロイ、MCP Inspector を使用したテスト

# stdio (default)
node dist/src/index.js

# HTTP on 127.0.0.1:3001
MCP_TRANSPORT=http node dist/src/index.js

# Custom HTTP host/port
MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=8080 node dist/src/index.js

🔧 環境変数

データベース接続

変数	必須	既定値	説明
DB_SERVER	✅	—	SQL Server のホスト名または IP
DB_DATABASE	❌	—	データベース名
DB_USER	❌	—	ログインユーザー名
DB_PASSWORD	❌	—	ログインパスワード
DB_PORT	❌	1433	TCP ポート
DB_ENCRYPT	❌	true	TLS を有効にします（Azure SQL では必須）
DB_TRUST_SERVER_CERTIFICATE	❌	false	自己署名証明書を信頼します
DB_CONNECTION_TIMEOUT	❌	30000	接続タイムアウト（ミリ秒）
DB_REQUEST_TIMEOUT	❌	30000	クエリタイムアウト（ミリ秒）

トランスポート

変数	デフォルト	説明
MCP_TRANSPORT	stdio	stdio または http
MCP_HOST	127.0.0.1	HTTP バインドアドレス
MCP_PORT	3001	HTTP ポート

🔒 セキュリティモデル

• 認証情報パラメーターなし：すべての接続設定は環境変数からのみ取得されます。ツールの入力で接続設定を上書きすることはできません。
• 識別子の検証：スキーマ名、テーブル名、プロシージャ名は、SQL に埋め込む前に安全な識別子パターンと照合して検証されます。
• パラメーター化クエリ：ユーザー指定の値（WHERE 句の値、列の値）はすべて、名前付きパラメーター @paramName として渡す必要があります。クエリ文字列に直接埋め込まないでください。
• Origin と Host の検証：HTTP トランスポートは、Origin ヘッダーと Host ヘッダーの両方を許可リスト（デフォルトでは localhost、[::1]、および設定されたバインドホスト）と照合して検証し、DNS リバインディングを防ぎます。
• SQL リスクのラベル付け：run_sql_query と execute_stored_procedure は、読み取り専用ではなくオープンワールドであることが明示されています。

⚠️ SQL のリスクに関する注意

run_sql_query は、DDL や DML を含む任意の SQL を受け付けます。リスクを最小限に抑えるには、次の点に注意してください。

• 最小権限の SQL ログインを使用します（可能な場合は SELECT のみ）。
• sysadmin または sa アカウントでサーバーを実行しないでください。
• サーバーがアクセスできる範囲を制限するため、ネットワークファイアウォールルールの設定を検討してください。

📄 ページネーション

すべてのリストツールは pagination オブジェクトを返します。

{
  "count": 20,
  "limit": 20,
  "offset": 0,
  "has_more": true,
  "next_offset": 20,
  "total_count": 150
}

デフォルトのページサイズ：20 行。最大：200 行。

シリアライズされたペイロードが 100KB を超えた場合も結果は切り捨てられ、削除された行数を示す truncation_message が付加されます。

🏗️ アーキテクチャ

src/
  index.ts          ← bootstrap (env, transport selection)
  server.ts         ← createServer() factory
  constants.ts      ← limits, defaults, protocol strings
  config.ts         ← env parsing
  types.ts          ← shared TypeScript interfaces
  db/
    connection.ts   ← connection pool singleton
    validators.ts   ← SQL identifier validation
    query-builders.ts ← safe parameterized query construction
  tools/            ← one file per tool group
  resources/        ← MCP resource handlers
  transports/       ← stdio and HTTP transports
  utils/
    errors.ts       ← error normalization helpers
    format.ts       ← JSON formatting, payload truncation
    markdown.ts     ← markdown table/list rendering helpers
    pagination.ts   ← pagination metadata helpers

🧪 Inspector のスモークテスト

npx @modelcontextprotocol/inspector

期待される結果：

• stdio サーバーが接続される
• すべてのツールを含むツール一覧が表示される
• 接続がなくても mssql_connection_status が JSON を返す
• 環境変数が設定されている場合、mssql_connect_database が動作する

🔨 開発

npm install
cp .env.example .env  # fill in your test DB credentials
npm run typecheck     # type check only
npm run build         # compile TypeScript
npm test              # run unit tests
npm run ci            # typecheck + build + test

ライセンス

MIT © BYMCS