Sql MCP Mac Windows

🚀 SQL Server MCP - 用於人工智能的跨平臺數據庫集成

SQL Server MCP 是一個基於 Model Context Protocol (MCP) 的服務器實現，它使人工智能助手能夠通過自然語言探索和查詢 SQL Server 數據庫。該系統作為一個專為數據庫知識探索優化的 RAG（檢索增強生成）系統構建。

🚀 快速開始

本倉庫包含兩個特定平臺的實現：

Windows 版本 →

• ✅ Windows 身份驗證（ODBC 驅動 17）
• ✅ SQL Server 身份驗證
• ✅ 原生 msnodesqlv8 驅動以實現最佳性能
• 📖 Windows 安裝指南

macOS 版本 →

• ✅ SQL Server 身份驗證（需要 Docker）
• ✅ 純 JavaScript mssql 驅動（無原生依賴）
• 📖 macOS 安裝指南

✨ 主要特性

• 🔍 模式探索 - 列出數據庫、表、視圖、存儲過程
• 🔗 關係映射 - 發現外鍵關係和表依賴
• 🔎 搜索與發現 - 跨表、列、過程進行全局模式搜索
• ⚡ 安全查詢執行 - 具有自動超時和行限制的只讀 SELECT 查詢
• 🗄️ 模式緩存 - 可配置 TTL 的快速檢索（默認：60 分鐘）
• 🔐 安全至上 - 默認只讀，防止 SQL 注入，查詢驗證
• 🖥️ 跨平臺 - 原生 Windows 身份驗證和 macOS Docker 支持

🎥 演示

查看 SQL Server MCP 與人工智能助手集成的實際操作：

注意：觀看自然語言查詢如何立即探索數據庫模式、查找關係並檢索數據 - 所有操作都無需離開你的人工智能助手！

📦 安裝指南

🎉 現已在 MCP 註冊表中可用！

此服務器已正式發佈在 Model Context Protocol 註冊表 中：

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

🚀 快速開始（推薦）

無需安裝！只需將其添加到你的人工智能助手配置中：

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"
      }
    }
  }
}

重啟你的人工智能助手，即可開始使用！

🛠️ 開發設置

對於開發或本地修改：

Windows

cd sql-server-mcp
npm install
npm run build

👉 完整的 Windows 設置說明

macOS

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

👉 完整的 macOS 設置說明

💻 使用示例

配置完成後，你可以向你的人工智能助手提問：

"此服務器上有哪些數據庫可用？"

"顯示 Sales 數據庫中的所有表"

"Orders 表的模式是什麼？"

"查找所有引用 Customers 表的表"

"搜索與 'email' 相關的任何列"

"執行：SELECT TOP 10 * FROM Products ORDER BY Price DESC"

📚 詳細文檔

🛠️ 可用的 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 查詢

⚙️ 配置

兩個版本都使用環境變量進行配置：

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                    # 此文件

🎯 使用場景

數據庫探索

• "此數據庫中存在哪些表？"
• "顯示 Users 表的結構"
• "列出所有存儲過程"

模式研究

• "查找所有包含 'email' 列的表"
• "搜索與 'invoice' 相關的任何內容"
• "有哪些視圖可用？"

關係分析

• "Orders 和 Customers 之間有什麼關係？"
• "顯示所有引用 Products 表的表"
• "此表的外鍵關係是什麼？"

數據查詢

• "獲取前 10 個最昂貴的產品"
• "顯示最近的訂單"
• "每個表中的記錄總數是多少？"

📄 許可證

本項目採用 MIT 許可證 - 有關詳細信息，請參閱 LICENSE 文件。

🙏 致謝

• 基於 Model Context Protocol SDK 構建
• 使用 mssql 和 msnodesqlv8 驅動
• 受更好的人工智能與數據庫集成需求的啟發

📚 資源

• Windows 安裝指南：
• macOS 安裝指南：
• 故障排除：查看特定平臺的 TROUBLESHOOTING.md 文件
• MCP 文檔：https://github.com/modelcontextprotocol
• 報告問題：https://github.com/TharanaBope/SQL-MCP-Mac-Windows/issues

🌐 特定平臺文檔

為 MCP 社區用心打造 ❤️

⭐ 如果你覺得有用，請給這個倉庫加星！ 🐛 通過 問題 報告錯誤 💬 有問題？ 查看 討論