SQL Server MCP (macOS)

SQL Server MCP - AI 向けクロスプラットフォームデータベース連携

AI アシスタントが自然言語を通じて SQL Server データベースを探索、検索できるようにする、SQL Server 用の Model Context Protocol（MCP） サーバー実装です。データベースのナレッジ探索に最適化された RAG（検索拡張生成）システムとして構築されています。

🌟 機能

• 🔍 スキーマの探索 - データベース、テーブル、ビュー、ストアドプロシージャの一覧表示
• 🔗 リレーションシップのマッピング - 外部キーのリレーションシップとテーブルの依存関係を検出
• 🔎 検索と検出 - テーブル、列、プロシージャを横断したスキーマのグローバル検索
• ⚡ 安全なクエリ実行 - 自動タイムアウトと行数制限を備えた読み取り専用の SELECT クエリ
• 🗄️ スキーマのキャッシュ - 設定可能な TTL（デフォルト：60 分）による高速な取得
• 🔐 セキュリティ優先 - デフォルトで読み取り専用、SQL インジェクションの防止、クエリの検証
• 🖥️ クロスプラットフォーム - Windows 認証と macOS Docker をネイティブサポート

🎥 デモ

AI アシスタントとの連携による SQL Server MCP の動作をご覧ください。

注： 自然言語のクエリによって、AI アシスタントから離れることなく、データベーススキーマをすぐに探索し、リレーションシップを見つけ、データを取得できる様子をご覧ください。

🚀 クイックスタート

このリポジトリには、プラットフォーム別の実装が 2 つ含まれています。

Windows 版 → sql-server-mcp/

• ✅ Windows 認証（ODBC Driver 17）
• ✅ SQL Server 認証
• ✅ 最適なパフォーマンスを実現するネイティブの msnodesqlv8 ドライバー
• 📖 Windows セットアップガイド

macOS 版 → sql-server-mcp-mac/

• ✅ SQL Server 認証（Docker が必要）
• ✅ 純粋な JavaScript の mssql ドライバー（ネイティブ依存関係なし）
• 📖 macOS セットアップガイド

📦 インストール

🎉 MCP レジストリで公開されました！

このサーバーは Model Context Protocol Registry に正式に公開されています。

• Windows：io.github.TharanaBope/sql-server-mcp
• macOS：io.github.TharanaBope/sql-server-mcp-macos

🚀 クイックスタート（推奨）

インストールは不要です。AI アシスタントの設定に追加するだけです。

Claude Desktop（Windows）

設定ファイルの場所：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "sql-server": {
      "command": "npx",
      "args": ["-y", "@tharanabopearachchi/sql-server-mcp@latest"],
      "env": {
        "SQL_SERVER": "localhost",
        "SQL_DATABASE": "master",
        "SQL_USE_WINDOWS_AUTH": "true"
      }
    }
  }
}

Claude Desktop（macOS）

設定ファイルの場所：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "sql-server": {
      "command": "npx",
      "args": ["-y", "@tharanabopearachchi/sql-server-mcp-macos@latest"],
      "env": {
        "SQL_SERVER": "localhost",
        "SQL_DATABASE": "master",
        "SQL_USE_WINDOWS_AUTH": "false",
        "SQL_USERNAME": "sa",
        "SQL_PASSWORD": "your_password"
      }
    }
  }
}

{
  "mcpServers": {
    "sql-server": {
      "command": "npx",
      "args": ["-y", "@tharanabopearachchi/sql-server-mcp@latest"],
      "env": {
        "SQL_SERVER": "localhost",
        "SQL_DATABASE": "master",
        "SQL_USE_WINDOWS_AUTH": "true",
        "SQL_USERNAME": "",
        "SQL_PASSWORD": ""
      }
    }
  }
}

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@tharanabopearachchi/sql-server-mcp@latest"]
        },
        "env": {
          "SQL_SERVER": "localhost",
          "SQL_DATABASE": "master",
          "SQL_USE_WINDOWS_AUTH": "true"
        }
      }
    ]
  }
}

{
  "mcpServers": {
    "sql-server": {
      "command": "npx",
      "args": ["-y", "@tharanabopearachchi/sql-server-mcp@latest"],
      "env": {
        "SQL_SERVER": "localhost",
        "SQL_DATABASE": "master",
        "SQL_USE_WINDOWS_AUTH": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "sql-server": {
      "command": "npx",
      "args": ["-y", "@tharanabopearachchi/sql-server-mcp@latest"],
      "env": {
        "SQL_SERVER": "localhost",
        "SQL_DATABASE": "master",
        "SQL_USE_WINDOWS_AUTH": "true"
      }
    }
  }
}

AI アシスタントを再起動すれば、すぐに使い始められます。

🛠️ 開発環境のセットアップ

開発またはローカルでの変更を行う場合：

Windows

cd sql-server-mcp
npm install
npm run build

👉 Windows のセットアップ手順（完全版）

macOS

cd sql-server-mcp-mac
npm install
npm run build

👉 macOS セットアップ手順（完全版）

🛠️ 利用可能な MCP ツール

このサーバーは、データベースを調査するための強力なツールを12個提供します。

スキーマの調査

• list_databases - 利用可能なすべてのデータベースを確認
• list_tables - 行数とともにテーブルを表示
• describe_table - 詳細なスキーマを取得（列、型、制約、インデックス）
• list_views - すべてのビューを一覧表示
• list_stored_procedures - メタデータとともにストアドプロシージャを一覧表示
• get_procedure_definition - SQL 定義全体を取得
• get_database_overview - 概要統計を取得

リレーションシップのマッピング

• get_table_relationships - 外部キーのリレーションシップを取得（参照元・参照先）
• get_related_tables - 直接つながっているテーブルを検索

検索と探索

• search_schema - テーブル、列、ビュー、プロシージャを横断して検索
• find_column_usage - 特定の列を含むすべてのテーブルを検索

クエリの実行

• execute_query - 読み取り専用の SELECT クエリを安全に実行

💬 使用例

設定が完了したら、AI アシスタントに次のように質問できます。

"What databases are available on this server?"

"Show me all tables in the Sales database"

"What's the schema of the Orders table?"

"Find all tables that reference the Customers table"

"Search for any columns related to 'email'"

"Execute: SELECT TOP 10 * FROM Products ORDER BY Price DESC"

⚙️ 設定

どちらのバージョンも、設定に環境変数を使用します。

SQL_SERVER=localhost
SQL_DATABASE=master
SQL_PORT=1433
SQL_USE_WINDOWS_AUTH=true          # Windows only
SQL_USERNAME=                       # For SQL Auth
SQL_PASSWORD=                       # For SQL Auth
QUERY_TIMEOUT=30
MAX_RESULT_ROWS=1000
ENABLE_SCHEMA_CACHE=true
CACHE_TTL_MINUTES=60

詳しい設定手順については、プラットフォームごとの README をご覧ください。

🔐 セキュリティ機能

• ✅ デフォルトで読み取り専用 - 明示的に有効化しない限り、書き込み操作は無効です
• ✅ クエリの検証 - デフォルトでは SELECT 文のみ許可されます
• ✅ タイムアウトの自動設定 - 長時間実行されるクエリを防止します
• ✅ 行数制限 - メモリの枯渇を防ぎます
• ✅ SQL インジェクションの防止 - クエリのサニタイズと検証
• ✅ データベースのホワイトリスト化 - 特定のデータベースのみに任意で制限できます

🏗️ アーキテクチャ

MCP/
├── sql-server-mcp/              # Windows implementation
│   ├── src/
│   │   ├── index.ts             # MCP server entry point
│   │   ├── database/            # Connection, caching, queries
│   │   ├── tools/               # 12 MCP tools
│   │   └── types/               # TypeScript interfaces
│   ├── dist/                    # Compiled output
│   ├── package.json
│   └── README.md                # Windows documentation
│
├── sql-server-mcp-mac/          # macOS implementation
│   ├── src/                     # Same structure as Windows
│   └── README.md                # macOS documentation
│
├── LICENSE                      # MIT License
└── README.md                    # This file

🎯 ユースケース

データベースの調査

• 「このデータベースにはどんなテーブルがありますか？」
• 「Users テーブルの構造を表示してください」
• 「すべてのストアドプロシージャを一覧表示してください」

スキーマの調査

• 「'email' 列があるすべてのテーブルを検索してください」
• 「'invoice' に関連するものをすべて検索してください」
• 「どのビューを利用できますか？」

リレーションシップの分析

• 「Orders と Customers はどのように関連していますか？」
• 「Products を参照しているすべてのテーブルを表示してください」
• 「このテーブルの外部キーのリレーションシップを教えてください」

データクエリ

• 「最も高価な商品の上位10件を取得してください」
• 「最近の注文を表示してください」
• 「各テーブルのレコード数の合計はいくつですか？」

🤝 貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。大きな変更を行う場合は、まず issue を作成して、変更内容について相談してください。

📄 ライセンス

このプロジェクトは MIT ライセンスのもとで公開されています。詳しくは LICENSE ファイルをご覧ください。

🙏 謝辞

• Model Context Protocol SDK を基盤に構築
• mssql および msnodesqlv8 ドライバーを使用
• AI とデータベースのより良い連携を求める声に着想を得て開発

📚 リソース

• Windows セットアップガイド：sql-server-mcp/README.md
• macOS セットアップガイド：sql-server-mcp-mac/README.md
• トラブルシューティング：プラットフォームごとの TROUBLESHOOTING.md ファイルをご確認ください
• MCP ドキュメント：https://github.com/modelcontextprotocol
• 問題の報告：https://github.com/TharanaBope/SQL-MCP-Mac-Windows/issues

🌐 プラットフォームごとのドキュメント

MCP コミュニティのために ❤️ を込めて作成

⭐ 役に立ったら、このリポジトリにスターを付けてください！ 🐛 Issues からバグを報告してください 💬 質問がありますか？ Discussions をご確認ください