Sql MCP Mac Windows

🚀 SQL Server MCP - AI用クロスプラットフォームデータベース統合

SQL Server MCPは、AIアシスタントが自然言語でSQL Serverデータベースを探索およびクエリできるようにする、データベース知識探索に最適化されたRAG（Retrieval-Augmented Generation）システムです。

✨ 主な機能

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

🎥 デモ

AIアシスタントとの統合でSQL Server MCPを実際に動作させる様子を見ることができます。

注意: 自然言語クエリがデータベーススキーマを瞬時に探索し、関係を見つけ、データを取得する様子をご覧ください。これらはすべてAIアシスタントから離れることなく行えます。

🚀 クイックスタート

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

Windows版 →

• ✅ Windows認証 (ODBC Driver 17)
• ✅ SQL Server認証
• ✅ 最適なパフォーマンスを得るためのネイティブmsnodesqlv8ドライバ
• 📖 Windowsセットアップガイド

macOS版 →

• ✅ 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のみ
SQL_USERNAME=                       # SQL認証用
SQL_PASSWORD=                       # SQL認証用
QUERY_TIMEOUT=30
MAX_RESULT_ROWS=1000
ENABLE_SCHEMA_CACHE=true
CACHE_TTL_MINUTES=60

詳細な設定手順については、プラットフォーム固有のREADMEを参照してください。

🔐 セキュリティ機能

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

🏗️ アーキテクチャ

MCP/
├── sql-server-mcp/              # Windows実装
│   ├── src/
│   │   ├── index.ts             # MCPサーバーのエントリポイント
│   │   ├── database/            # 接続、キャッシュ、クエリ
│   │   ├── tools/               # 12のMCPツール
│   │   └── types/               # TypeScriptインターフェース
│   ├── dist/                    # コンパイルされた出力
│   ├── package.json
│   └── README.md                # Windows用ドキュメント
│
├── sql-server-mcp-mac/          # macOS実装
│   ├── src/                     # Windowsと同じ構造
│   └── README.md                # macOS用ドキュメント
│
├── LICENSE                      # MITライセンス
└── README.md                    # このファイル

🎯 ユースケース

データベース探索

• "このデータベースに存在するテーブルは何ですか？"
• "Salesデータベース内のすべてのテーブルを表示してください"
• "すべてのストアドプロシージャを一覧表示してください"

スキーマ調査

• "email列を持つすべてのテーブルを見つけてください"
• "invoiceに関連するすべてのものを検索してください"
• "利用可能なビューは何ですか？"

リレーションシップ分析

• "OrdersテーブルとCustomersテーブルはどのように関連していますか？"
• "Productsテーブルを参照するすべてのテーブルを表示してください"
• "このテーブルの外部キー関係は何ですか？"

データクエリ

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

🤝 コントリビューション

コントリビューションは歓迎されます！プルリクエストを送信してください。大規模な変更の場合は、まず問題を開いて、変更したい内容について議論してください。

📄 ライセンス

このプロジェクトは、MITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

🙏 謝辞

• Model Context Protocol SDKをベースに構築されています。
• mssqlとmsnodesqlv8ドライバを使用しています。
• AIとデータベースの統合の必要性に触発されています。

📚 リソース

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

🌐 プラットフォーム固有のドキュメント

MCPコミュニティのために愛情を込めて作られました

⭐ このリポジトリをスター もし役に立つと思ったら！ 🐛 バグの報告 Issues を通して！ 💬 質問がある場合 Discussions をチェックしてください！