MS SQL MCP サーバー 1.1

ClaudeのようなAIアシスタントがMicrosoft SQL Serverデータベースに直接クエリを実行し、探索できるようにする、使いやすいブリッジです。コーディング経験は必要ありません。

このツールは何をするのですか?

このツールにより、AI アシスタントは次のことが可能になります。

SQL Server データベース内のテーブルを検出する
テーブル構造（列、データ型など）を表示します
読み取り専用SQLクエリを安全に実行する
自然言語リクエストからSQLクエリを生成する

🌟 このツールが必要な理由

データとAIのギャップを埋める

コーディング不要: 複雑な統合コードを書かずに、Claude や他の AI アシスタントに SQL Server データベースへの直接アクセスを許可します。
制御を維持: すべてのクエリはデフォルトで読み取り専用であるため、データの安全性が確保されます。
プライベートかつ安全: データベースの認証情報はローカルに保存され、外部サービスに送信されることはありません

実用的なメリット

手作業の時間を節約：AIと共有するためにデータやクエリ結果をコピー＆ペーストする必要がなくなります
より深い分析: AI はデータベーススキーマ全体をナビゲートし、複数のテーブルにわたる洞察を提供できます。
自然言語インターフェース: わかりやすい英語でデータについて質問できます
コンテキスト制限問題の解消: 通常の AI コンテキストウィンドウを超える大規模なデータセットにアクセスします。

最適です

資格情報を共有せずにSQLデータの解釈をAIに支援してもらいたいデータアナリスト
自然な会話を通じてデータベース構造を素早く探索する方法を探している開発者
SQL の専門知識がなくても洞察力を必要とするビジネスアナリスト
AIツールへの制御されたアクセスを提供したいデータベース管理者

🚀 クイックスタートガイド

ステップ1: 前提条件をインストールする

Node.js （バージョン14以上）をインストールする
Microsoft SQL Server データベース (オンプレミスまたは Azure) にアクセスできる

ステップ2: クローンとセットアップ

# Clone this repository
git clone https://github.com/dperussina/mssql-mcp-server.git

# Navigate to the project directory
cd mssql-mcp-server

# Install dependencies
npm install

# Copy the example environment file
cp .env.example .env

ステップ3: データベース接続を構成する

データベースの資格情報を使用して.envファイルを編集します。

DB_USER=your_username
DB_PASSWORD=your_password
DB_SERVER=your_server_name_or_ip
DB_DATABASE=your_database_name
PORT=3333
TRANSPORT=stdio
SERVER_URL=http://localhost:3333
DEBUG=false                     # Set to 'true' for detailed logging (helpful for troubleshooting)
QUERY_RESULTS_PATH=/path/to/query_results  # Directory where query results will be saved as JSON files

ステップ4: サーバーを起動する

# Start with default stdio transport
npm start

# OR start with HTTP/SSE transport for network access
npm run start:sse

ステップ 5: 試してみましょう!

# Run the interactive client
npm run client

📊 使用例

SQLを書かずにデータベース構造を探索する
mcp_SQL_mcp_discover_database()
特定のテーブルに関する詳細情報を取得する
mcp_SQL_mcp_table_details({ tableName: "Customers" })
安全なクエリを実行する
mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Customers", returnResults: true })
名前のパターンでテーブルを検索する
mcp_SQL_mcp_discover_tables({ namePattern: "%user%" })
ページネーションを使用して大規模な結果セットをナビゲートする
// First page mcp_SQL_mcp_execute_query({ sql: "SELECT * FROM Users ORDER BY Username OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY", returnResults: true }) // Next page mcp_SQL_mcp_execute_query({ sql: "SELECT * FROM Users ORDER BY Username OFFSET 10 ROWS FETCH NEXT 10 ROWS ONLY", returnResults: true })
最適なパフォーマンスを実現するカーソルベースのページネーション
// First page mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Users ORDER BY Username", returnResults: true }) // Next page using the last value as cursor mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Users WHERE Username > 'last_username' ORDER BY Username", returnResults: true })
自然言語で質問する
"Show me the top 5 customers with the most orders in the last month"

💡 実世界への応用

ビジネスインテリジェンス向け

売上実績分析: 「過去 1 年間の月別売上傾向を示し、地域別に最も売れている製品を特定します。」
顧客セグメンテーション: 「購入頻度、平均注文額、地理的な場所別に顧客ベースを分析します。」
財務報告：「今年と昨年を比較した四半期損益レポートを作成します。」

データベース管理用

スキーマの最適化: 「クエリパフォーマンスデータを調べて、インデックスが欠落しているテーブルを特定するのに役立ちます。」
データ品質監査:「不完全な情報または無効な値を持つすべての顧客レコードを検索します。」
使用状況分析: 「最も頻繁にアクセスされるテーブルと、最もリソースを消費するクエリを表示します。」

開発のために

API 探索: 「API を構築しています。適切なエンドポイントを設計するためにデータベーススキーマの分析を手伝ってください。」
クエリの最適化: 「この複雑なクエリを確認し、パフォーマンスの改善を提案します。」
データベースドキュメント: 「関係の説明を含むデータベース構造の包括的なドキュメントを作成します。」

🖥️ インタラクティブクライアント機能

バンドルされたクライアントは、簡単なメニュー駆動型のインターフェースを提供します。

利用可能なリソースの一覧- 利用可能な情報を確認する
利用可能なツールの一覧- 実行できるアクションを確認する
SQLクエリの実行- 読み取り専用のSQLクエリを実行する
テーブルの詳細を取得- 任意のテーブルの構造を表示します
データベーススキーマの読み取り- すべてのテーブルとその関係を確認する
SQLクエリを生成- 自然言語をSQLに変換する

🧠 効果的なプロンプトとツールの使用ガイド

このMCPサーバーを介してClaudeや他のAIアシスタントと連携する場合、リクエストの表現方法が結果に大きな影響を与えます。AIがデータベースツールを効果的に使用できるようにするには、以下の手順を実行してください。

基本的なツール呼び出し形式

AI にこのツールを使用するように指示する場合は、次の構造に従います。

Can you use the SQL MCP tools to [your goal]?

For example:
- Check what tables exist in my database
- Query the Customers table and show me the first 10 records
- Find all orders from the past month

基本的なコマンドと構文

主なツールとその正しい構文は次のとおりです。

// Discover the database structure
mcp_SQL_mcp_discover_database()

// Get detailed information about a specific table
mcp_SQL_mcp_table_details({ tableName: "YourTableName" })

// Execute a query and return results
mcp_SQL_mcp_execute_query({ 
  sql: "SELECT * FROM YourTable WHERE Condition", 
  returnResults: true 
})

// Find tables by name pattern
mcp_SQL_mcp_discover_tables({ namePattern: "%pattern%" })

// Access saved query results (for large result sets)
mcp_SQL_mcp_get_query_results({ uuid: "provided-uuid-here" })

各ツールを使用するタイミング:

データベースの検出: AI がデータベース構造に慣れていない場合は、これから始めます。
テーブルの詳細: クエリを記述する前に特定のテーブルに焦点を当てる場合に使用します。
クエリ実行: 実際のデータを取得または分析する必要がある場合。
パターンによるテーブル検出: 特定のドメインに関連するテーブルを検索する場合。

効果的なプロンプトパターン

ステップバイステップのワークフロー

複雑なタスクの場合は、一連の手順で AI をガイドします。

I'd like to analyze our sales data. Please:
First use mcp_SQL_mcp_discover_tables to find tables related to sales
Use mcp_SQL_mcp_table_details to examine the structure of relevant tables
Create a query with mcp_SQL_mcp_execute_query that shows monthly sales by product category

まず構造を作り、次にクエリを実行する

First, discover what tables exist in my database. Then, look at the structure
of the Customers table. Finally, show me the top 10 customers by total purchase amount.

説明を求める

Query the top 5 underperforming products based on sales vs. forecasts,
and explain your approach to writing this query.

SQL Server 方言に関する注意事項

SQL Server の特定の構文について AI に思い出させます。

Please use SQL Server syntax for pagination:
- For offset/fetch: "OFFSET 10 ROWS FETCH NEXT 10 ROWS ONLY"
- For cursor-based: "WHERE ID > last_id ORDER BY ID"

ツールの使用法の修正

AI が誤った構文を使用する場合は、次の方法で支援できます。

That's not quite right. Please use this format for the tool call:
mcp_SQL_mcp_execute_query({ 
  sql: "SELECT * FROM Customers WHERE Region = 'West'",
  returnResults: true
})

プロンプトによるトラブルシューティング

AI がデータベースタスクに苦労している場合は、次のアプローチを試してください。

テーブルについてより具体的に説明します。 「クエリを記述する前に、CustomerOrders テーブルが存在するかどうか、また、そのテーブルにどのような列があるかを確認してください。」
複雑なタスクをステップに分割します。 「ステップごとに進めていきましょう。まず、Products テーブルの構造を確認します。次に、Orders テーブルを確認します...」
中間結果を求める: 「まずそのテーブルで簡単なクエリを実行して、より複雑な分析を試す前にデータ形式を確認します。」
クエリの説明をリクエストします。 「このクエリを記述した後、各部分で何が行われるかを説明してください。そうすれば、必要な処理が実行されていることを確認できます。」

🔎 高度なクエリ機能

テーブル発見と探索

MCP サーバーは、データベース構造を探索するための強力なツールを提供します。

パターンベースのテーブル検出: 特定のパターンに一致するテーブルを検索します
mcp_SQL_mcp_discover_tables({ namePattern: "%order%" })
スキーマの概要: スキーマごとにテーブルの概要を取得します
mcp_SQL_mcp_execute_query({ sql: "SELECT TABLE_SCHEMA, COUNT(*) AS TableCount FROM INFORMATION_SCHEMA.TABLES GROUP BY TABLE_SCHEMA" })
列の探索: 任意のテーブルの列のメタデータを調べる
mcp_SQL_mcp_table_details({ tableName: "dbo.Users" })

ページネーションテクニック

サーバーは、大規模なデータセットを処理するために複数のページ区切り方法をサポートしています。

オフセット/フェッチページネーション: OFFSETとFETCHを使用した標準SQLページネーション
mcp_SQL_mcp_execute_query({ sql: "SELECT * FROM Users ORDER BY Username OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY" })
カーソルベースのページネーション: 大規模なデータセットでより効率的
// Get first page mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Users ORDER BY Username" }) // Get next page using last value as cursor mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Users WHERE Username > 'last_username' ORDER BY Username" })
データ付きカウント: ページ区切りデータとともに合計数を取得します
mcp_SQL_mcp_execute_query({ sql: "WITH TotalCount AS (SELECT COUNT(*) AS Total FROM Users) SELECT TOP 10 u.*, t.Total FROM Users u CROSS JOIN TotalCount t ORDER BY Username" })

複雑な結合と関係

結合操作を使用してテーブル間の関係を調査します。

mcp_SQL_mcp_execute_query({ 
  sql: "SELECT u.Username, u.Email, r.RoleName FROM Users u JOIN UserRoles ur ON u.Username = ur.Username JOIN Roles r ON ur.RoleId = r.RoleId ORDER BY u.Username"
})

分析クエリ

集計と分析クエリを実行して洞察を獲得します。

mcp_SQL_mcp_execute_query({ 
  sql: "SELECT UserType, COUNT(*) AS UserCount, SUM(CASE WHEN IsActive = 1 THEN 1 ELSE 0 END) AS ActiveUsers FROM Users GROUP BY UserType"
})

SQL Server 機能の使用

MCP サーバーは、SQL Server 固有の機能をサポートしています。

共通テーブル式（CTE）
ウィンドウ関数
JSON操作
階層クエリ
全文検索（データベースに設定されている場合）

🔗 統合オプション

クロードデスクトップ統合

次の簡単な手順で、このツールを Claude Desktop に直接接続します。

anthropic.comからClaude Desktopをインストールする
Claude の設定ファイルを編集します。
- 場所: ~/Library/Application Support/Claude/claude_desktop_config.json
- 次の構成を追加します。

{
    "mcpServers": {
        "mssql": {
            "command": "node",
            "args": [
                "/FULL/PATH/TO/mssql-mcp-server/server.mjs"
            ]
        }
    }
}

/FULL/PATH/TO/このリポジトリをクローンした実際のパスに置き換えます。
Claudeデスクトップを再起動します
Claude Desktop のツールアイコンを探してください。データベースコマンドを直接使用できるようになりました。

カーソルIDEとの接続

CursorはAIを搭載したコードエディタで、高度なデータベース操作にこのツールを活用できます。設定方法は以下の通りです。

カーソルで設定

Open Cursor IDE を開きます (お持ちでない場合は、 cursor.shからダウンロードしてください)
HTTP/SSE トランスポートを使用して MS SQL MCP サーバーを起動します。
npm run start:sse
カーソルで新しいワークスペースを作成するか、既存のプロジェクトを開きます
カーソル設定を入力
MCPをクリック
新しいMCPサーバーを追加する
MCPサーバーに名前を付け、タイプを選択します: sse
サーバーの URL を次のように入力します: localhost:3333/sse (または実行しているポート)

カーソル内でのデータベースコマンドの使用

接続すると、Cursor の AI チャットで直接 MCP コマンドを使用できるようになります。

Cursor の Claude にデータベースを探索するよう依頼します。
Can you show me the tables in my database?
特定のクエリを実行します。
Query the top 10 records from the Customers table
複雑なクエリを生成して実行します。
Find all orders from the last month with a value over $1000

カーソル接続のトラブルシューティング

MS SQL MCPサーバーがHTTP/SSEトランスポートで実行されていることを確認してください
ポートが正しく、.env ファイルの内容と一致していることを確認してください。
ファイアウォールが接続をブロックしていないことを確認してください
異なるIP/ホスト名を使用する場合は、.envファイルのSERVER_URLを更新してください。

🔄 輸送方法の説明

オプション 1: stdio トランスポート (デフォルト)

最適な用途: Claude Desktop またはバンドルされたクライアントで直接使用

npm start

オプション2: HTTP/SSEトランスポート

最適な用途: ネットワークアクセスまたはWebアプリケーションで使用する場合

npm run start:sse

🛡️ セキュリティ機能

デフォルトで読み取り専用：データ変更のリスクなし
プライベート認証情報: データベース接続の詳細は.envファイルに残ります
SQLインジェクション保護: SQLクエリの組み込み検証

🔎 新規ユーザー向けトラブルシューティング

「データベースに接続できません」

.envファイルで正しいデータベース資格情報を確認してください
SQL Server が実行中で接続を受け入れていることを確認してください
Azure SQLの場合、ファイアウォール設定でIPが許可されていることを確認してください

「モジュールが見つかりません」エラー

すべての依存関係がインストールされていることを確認するためにnpm install再度実行します。
Node.jsバージョン14以上を使用していることを確認してください

「トランスポートエラー」または「接続拒否」

HTTP/SSEトランスポートの場合、.envのポートが利用可能であることを確認してください。
ファイアウォールが接続をブロックしていないことを確認してください

クロードデスクトップに接続できません

claude_desktop_config.jsonのパスを再確認してください
相対パスではなく絶対パスを使用していることを確認してください
変更を加えた後、Claude Desktopを完全に再起動してください。

📚 SQL Server の基礎を理解する

SQL Server を初めて使用する場合は、次の重要な概念を理解しておく必要があります。

表: データを行と列に保存します
スキーマ: テーブルの論理的なグループ（フォルダなど）
クエリ: データを取得または分析するためのコマンド
ビュー: 簡単にアクセスできるように保存された定義済みのクエリ

このツールを使用すると、SQL の専門家でなくてもこれらすべてを調べることができます。

🏗️ アーキテクチャとコアモジュール

MS SQL MCP サーバーは、保守性と拡張性に関する懸念を分離するモジュールアーキテクチャで構築されています。

コアモジュール

`database.mjs` - データベース接続

SQL Server 接続プールを管理します
再試行ロジックとエラー処理を備えたクエリ実行を提供します
データベース接続、トランザクション、構成を処理します
SQL およびフォーマットエラーをサニタイズするためのユーティリティが含まれています

`tools.mjs` - ツール登録

すべてのデータベースツールをMCPサーバーに登録します
ツールの検証とパラメータのチェックを実装します
SQLクエリ、テーブル探索、データベース検出のコア機能を提供します
ツール呼び出しをデータベース操作にマッピングする

`resources.mjs` - データベースリソース

リソースエンドポイントを通じてデータベースメタデータを公開する
スキーマ情報、テーブルリスト、および手順のドキュメントを提供します
AI で使用できるようにデータベース構造情報をフォーマットします
データベース探索用の検出ユーティリティが含まれています

`pagination.mjs` - 結果ナビゲーション

大規模な結果セットに対してカーソルベースのページ区切りを実装します
次/前のページカーソルを生成するためのユーティリティを提供します
ページ区切りをサポートするためにSQLクエリを変換します
SQL Server の OFFSET/FETCH ページ区切り構文を処理します

`errors.mjs` - エラー処理

さまざまな障害シナリオに合わせてカスタムエラータイプを定義します
JSON-RPCエラーフォーマットを実装
人間が読めるエラーメッセージを提供する
グローバルエラー処理用のミドルウェアが含まれています

`logger.mjs` - ログシステム

複数のトランスポートを使用して Winston のログを構成する
コンテキストに応じたリクエストログを提供する
ログのローテーションとフォーマットを処理
キャッチされていない例外と処理されていない拒否をキャプチャします

これらのモジュールがどのように連携するか

ツール呼び出しを受信すると、MCPサーバーはそれをtools.mjs内の適切なハンドラーにルーティングします。
ツールハンドラーはパラメータを検証し、データベースクエリを構築します。
クエリはdatabase.mjs内の関数を介して実行され、 pagination.mjsからのページネーションが可能です。
結果はフォーマットされてクライアントに返されます
エラーはすべてerrors.mjsを通じてキャッチされ、処理されます。
すべての操作はlogger.mjs経由で記録されます。

このアーキテクチャにより、次のことが保証されます。

明確な関心の分離
一貫したエラー処理
包括的なログ記録
効率的なデータベース接続管理
スケーラブルなクエリ実行

⚙️ 環境設定の説明

.envファイルは、MS SQL MCPサーバーがデータベースに接続し、動作する方法を制御します。各設定の詳細な説明は以下のとおりです。

# Database Connection Settings
DB_USER=your_username           # SQL Server username
DB_PASSWORD=your_password       # SQL Server password
DB_SERVER=your_server_name      # Server hostname or IP address (example: localhost, 10.0.0.1, myserver.database.windows.net)
DB_DATABASE=your_database_name  # Name of the database to connect to

# Server Configuration
PORT=3333                       # Port for the HTTP/SSE server to listen on
TRANSPORT=stdio                 # Connection method: 'stdio' (for Claude Desktop) or 'sse' (for network connections)
SERVER_URL=http://localhost:3333 # Base URL when using SSE transport (must match your PORT setting)

# Advanced Settings
DEBUG=false                     # Set to 'true' for detailed logging (helpful for troubleshooting)
QUERY_RESULTS_PATH=/path/to/query_results  # Directory where query results will be saved as JSON files

接続タイプの説明

stdioトランスポート

Claude Desktopに直接接続する場合に使用します
通信は標準入出力ストリームを通じて行われる
.envファイルでTRANSPORT=stdioを設定します
npm startで実行

HTTP/SSEトランスポート

ネットワーク経由で接続する場合に使用します（Cursor IDE など）
リアルタイム通信にサーバー送信イベント（SSE）を使用する
.envファイルでTRANSPORT=sseを設定します
SERVER_URLサーバーのアドレスに合わせて設定します
npm run start:sseで実行します。

SQL Server 接続の例

ローカル SQL サーバー

DB_USER=sa
DB_PASSWORD=YourStrongPassword
DB_SERVER=localhost
DB_DATABASE=AdventureWorks

Azure SQL データベース

DB_USER=azure_admin@myserver
DB_PASSWORD=YourStrongPassword
DB_SERVER=myserver.database.windows.net
DB_DATABASE=AdventureWorks

クエリ結果の保存

クエリ結果は、 QUERY_RESULTS_PATHで指定されたディレクトリにJSONファイルとして保存されます。これにより、結果セットが大量になって会話が過負荷になるのを防ぎます。以下のことが可能です。

プロジェクトのデフォルトのquery-resultsディレクトリを使用するには、これを空白のままにしておきます
/Users/username/Documents/query-resultsのようなカスタムパスを設定します
ツールの応答で提供された UUID を使用して保存された結果にアクセスします

📝 ライセンス

ISC