SQL Server MCP for Claude

Claude 用 SQL Server MCP

このリポジトリには、Claude 用の SQL Server MCP（Model Context Protocol）統合が含まれています。この統合により、Claude は自然言語を使って SQL Server データベースのデータを直接クエリし、分析できます。

この MCP サーバーは MCP Review の認定を受けています：https://mcpreview.com/mcp-servers/shakunvohradeltek/mcpserverformssql

概要

SQL MCP 統合は、次の手順で動作します。

1. Claude が Model Context Protocol 経由で通信できるローカルサーバーを設定します
2. pymssql を使って SQL Server データベースに直接接続します（ODBC は不要です）
3. Claude の自然言語によるリクエストを SQL クエリに変換します
4. クエリ結果を Claude に返し、解釈や提示を行います

重要なプロトコルに関する注意：この統合では、互換性を確保するため、Claude が必要とする MCP プロトコルのバージョン「2025-03-26」を使用します。この統合には、適切な JSON-RPC 形式や Content-Length ヘッダーを含め、プロトコルを正しく処理する固定の MCP 実装が含まれています。

主な機能

• ODBC 不要：pymssql を使って SQL Server に直接接続します
• シンプルなアーキテクチャ：依存関係を最小限に抑えた、わかりやすい設計です
• プロトコルのサポート：Claude の MCP システムで動作します
• クロスプラットフォーム：macOS と Linux で一貫して動作します
• 簡単なインストール：1 ステップでインストールできます
• スマートな設定：SQL サポートの追加時に、既存の MCP 設定と Claude の指示を保持します

インストール

前提条件

• macOS または Ubuntu Linux
• Python 3.7 以降
• FreeTDS（macOS では Homebrew 経由で自動的にインストールされます）
• Claude CLI（claude.ai/docs/installation からインストールしてください）
• 適切な権限を持つ SQL Server の認証情報（読み取り専用を推奨します。セキュリティ上の注意を参照してください）

インストール手順

1. インストールスクリプトを実行します。

./install_sql_mcp.sh

2. プロンプトに従って、SQL Server の接続情報を入力します。

   • SQL Server のホスト名
   • SQL Server のポート（デフォルト：1433）
   • データベース名
   • ユーザー名
   • パスワード
   • サーバー証明書を信頼するかどうか（デフォルト：true）

3. インストーラーによって、次の処理が行われます。

   • 必要な依存関係をインストールします
   • SQL Server への接続用に FreeTDS を設定します
   • Python 仮想環境をセットアップします
   • 必要な Python パッケージをインストールします
   • 必要なスクリプトを作成します
   • SQL MCP サーバーを認識するよう Claude を設定します

4. インストールを確認します。

./run_simple_sql.sh "SELECT 1 AS TestQuery"

使い方

1. Claude を起動します。

claude

次の操作もできます。

• MCP の状態を確認する：claude /mcp
• MCP をデバッグする：claude --mcp-debug

2. データベースについて Claude に質問します。

@sql execute_sql
SELECT TOP 5 * FROM YourTable

@sql execute_sql
SELECT COUNT(*) FROM Users WHERE IsActive = 1

⚠️ セキュリティ上の注意

重要： セキュリティ上の理由から、権限を制限したデータベースアカウントを使用してください。

• Claude がデータベースにアクセスするための、読み取り専用の専用ユーザーを作成してください
• DROP、DELETE、またはテーブル作成の権限を持つアカウントは使用しないでください
• 本番環境では、sa アカウントや管理者アカウントを決して使用しないでください
• 分析に必要な特定のテーブルまたはビューのみにアクセスを制限することを検討してください

権限が過剰なアカウントを使用すると、自然言語のリクエストに基づいて Claude が SQL クエリを生成した際、誤ってデータを失ったり、データベースの構造を変更したりする可能性があります。

Claude へのプロンプト作成のベストプラクティス

Claude を使用して SQL Server データベースを検索する際は、次のベストプラクティスに従ってください。

1. まず Claude にデータベーススキーマを調べてもらいます：クエリを作成する前に、データベースの構造を調べ、テーブル、カラム、リレーションシップを把握するよう Claude に指示します。

   @sql execute_sql
   SELECT TABLE_NAME, COLUMN_NAME, DATA_TYPE FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA = 'dbo' ORDER BY TABLE_NAME, ORDINAL_POSITION
   

2. データモデルに関するコンテキストを提供します：データベースにどのようなデータが含まれているか、またテーブル同士がどのように関連しているかを説明します。

3. スキーマの調査から始めます：複雑なクエリを作成する前に、まずテーブル構造を調べるよう Claude に依頼します。

4. クエリ結果を確認します：クエリ結果が何を意味するか Claude に説明してもらい、期待どおりの結果か確認します。

5. 段階的に複雑さを増やします：簡単なクエリから始め、Claude がスキーマを理解していることを確認しながら、徐々に複雑なクエリを追加します。

トラブルシューティング

SQL MCP との連携で問題が発生した場合は、次の手順を試してください。

1. 直接接続をテストします。

./run_simple_sql.sh "SELECT 1 AS TestQuery"

2. FreeTDS が正しく設定されていることを確認します。

tsql -C

3. Claude が MCP サーバーを見つけられることを確認します。

claude mcp list

4. 「Connection failed」または「Connection closed」というメッセージが表示されてもクエリが動作する場合は、これは正常な動作なので無視してかまいません。

5. プロトコルバージョンの互換性：このインストールでは、Claude の MCP に必要なプロトコルバージョン「2025-03-26」を使用します。MCP のトランスポートが閉じられたというエラーが発生した場合は、プロトコルバージョンが変更されていないか確認してください。

6. JSON-RPC 形式：Claude の MCP では、null ではない ID と Content-Length ヘッダーを含む、適切な JSON-RPC 形式が必要です。インストールスクリプトで正しく設定されます。

公開される MCP ツール

MCP サーバーは、次のツールを Claude に公開します。

execute_sql

• 説明：接続されたデータベースで SQL クエリを実行します
• 入力スキーマ：
  • query（string、必須）：実行する SQL クエリ
• 使用方法：Claude で @sql execute_sql に続けて SQL クエリを入力します
• 戻り値：クエリ結果、行数、成功ステータスを含む JSON オブジェクト

ファイルとコンポーネント

インストール時に作成されます。

• simple_sql.py - SQL クエリを直接処理する Python スクリプト
• run_simple_sql.sh - Python スクリプトを呼び出すラッパースクリプト
• mcp_fixed.py - ツールを適切に公開する MCP プロトコルの実装
• run_mcp_fixed.sh - MCP サーバー用のラッパースクリプト
• .mcp.json - MCP サーバーの設定ファイル
• CLAUDE.md - SQL 連携の使用方法を Claude に説明する手順書

チームへの配布

この SQL MCP 連携をチームに配布するには、次の手順に従ってください。

1. このリポジトリをチームメンバーと共有します

2. チームメンバーは次の作業を行います。

   • スクリプトに実行権限を付与します：chmod +x *.sh
   • インストールスクリプトを実行します：./install_sql_mcp.sh
   • プロンプトに従って SQL Server の詳細を入力します

最新の更新（2024 年 5 月）

インストールスクリプトが更新され、次の重要な修正が行われました。

1. Claude の要件に合わせて、MCP のプロトコルバージョンを「2025-03-26」に修正しました（以前は「2024-11-05」）。
2. JSON-RPC 形式を適切に処理する、改良された MCP 実装を追加しました。
3. MCP 通信で Content-Length ヘッダーを適切に処理するようにしました。
4. プロトコルの通知処理を修正しました。
5. MCP 接続を維持するための継続的なループを追加しました。
6. エラー処理とデバッグログを改善しました。
7. 新機能：MCP プロトコルを通じて SQL ツールを公開 - MCP サーバーが tools/list メソッドと tools/call メソッドを通じて execute_sql ツールを適切に公開するようになり、Claude のツール検索・実行システムと互換性を持つようになりました。

クレジット

この SQL MCP 連携は、次のオープンソースプロジェクトをベースにしています。

• FreeTDS - SQL Server との通信に使用する TDS プロトコルライブラリ
• pymssql - SQL Server 用の Python DB-API インターフェイス
• Model Context Protocol - Claude でのツール利用に関する Anthropic のプロトコル