MCP Sqlserver Pro

🚀 MSSQL MCP 服務器

MSSQL MCP 服務器是一個基於模型上下文協議（MCP）的服務器，它為訪問 Microsoft SQL Server 數據庫提供了全面的解決方案。藉助標準化接口，該服務器使語言模型能夠對數據庫架構進行檢查、執行查詢、管理數據庫對象以及執行高級數據庫操作。

🚀 快速開始

安裝

前提條件

• Python 3.10 或更高版本
• SQL Server 的 ODBC 驅動 17
• 能夠訪問 MSSQL Server 實例

快速設置

1. 克隆或創建項目目錄：

mkdir mcp-sqlserver && cd mcp-sqlserver

2. 運行安裝腳本：

chmod +x install.sh
./install.sh

3. 配置數據庫連接：

cp env.example .env
# 使用你的數據庫詳細信息編輯 .env 文件

手動安裝

1. 創建虛擬環境：

python3 -m venv venv
source venv/bin/activate

2. 安裝依賴項：

pip install -r requirements.txt

3. 安裝 ODBC 驅動（macOS）：

brew tap microsoft/mssql-release
brew install msodbcsql17 mssql-tools

配置

創建一個 .env 文件，並進行數據庫配置：

MSSQL_DRIVER={ODBC Driver 17 for SQL Server}
MSSQL_SERVER=your-server-address
MSSQL_DATABASE=your-database-name
MSSQL_USER=your-username
MSSQL_PASSWORD=your-password
MSSQL_PORT=1433
TrustServerCertificate=yes

配置選項

屬性	詳情
MSSQL_SERVER	服務器主機名或 IP 地址（必需）
MSSQL_DATABASE	要連接的數據庫名稱（必需）
MSSQL_USER	用於身份驗證的用戶名
MSSQL_PASSWORD	用於身份驗證的密碼
MSSQL_PORT	端口號（默認：1433）
MSSQL_DRIVER	ODBC 驅動名稱（默認：{ODBC Driver 17 for SQL Server}）
TrustServerCertificate	信任服務器證書（默認：yes）
Trusted_Connection	使用 Windows 身份驗證（默認：no）

運行服務器

與 AI 助手集成

python3 src/server.py

服務器將啟動並在標準輸入上等待 MCP 協議消息。像 Claude Desktop 這樣的 AI 助手或其他 MCP 客戶端將通過這種方式與它進行通信。

測試和開發

1. 測試數據庫連接：

python3 test_connection.py

2. 檢查服務器狀態：

./status.sh

3. 查看可用表：

# 服務器提供了可由 MCP 客戶端調用的工具
# 直接測試需要 MCP 客戶端或測試框架

✨ 主要特性

完整的數據庫架構遍歷

• 23 種全面的數據庫管理工具（從 5 種基本操作擴展而來）
• 完整的數據庫對象層次結構探索 - 表、視圖、存儲過程、索引、架構
• 高級數據庫對象管理 - 創建、修改、刪除操作
• 智能資源訪問 - 所有表和視圖都可作為 MCP 資源使用
• 大內容處理 - 可完整檢索存儲過程（1400 多行）而不截斷

核心功能

• 數據庫連接：通過靈活的身份驗證方式連接到 MSSQL Server 實例
• 架構檢查：完整的數據庫對象探索和管理
• 查詢執行：執行 SELECT、INSERT、UPDATE、DELETE 和 DDL 查詢
• 存儲過程管理：創建、修改、執行和管理存儲過程
• 視圖管理：創建、修改、刪除和描述視圖
• 索引管理：創建、刪除和分析索引
• 資源訪問：將表和視圖數據作為 MCP 資源瀏覽
• 安全性：讀寫操作進行了適當的分離和驗證

⚠️ 工程團隊重要使用指南

數據庫限制

🔴 重要提示：每個 MCP 服務器實例僅限使用一個數據庫

• 此增強型 MCP 服務器為每個數據庫創建 23 個工具
• 所有 MCP 服務器的遊標工具限制為 40 個
• 使用多個數據庫實例將超過遊標的工具限制
• 對於多個數據庫，請在不同項目中使用單獨的 MCP 服務器實例

大內容限制

⚠️ 重要提示：聊天上下文中不支持文件操作

• 大型存儲過程（1400 多行）可以在聊天中檢索和查看
• 但是，由於令牌限制，通過 MCP 工具將大內容保存到文件中不可靠
• 批量數據提取：使用直接連接數據庫的獨立 Python 腳本
• 推薦方法：從聊天中複製粘貼較小的存儲過程，對大型存儲過程使用外部腳本

工具分佈

• 核心工具：5 個（read_query、write_query、list_tables、describe_table、create_table）
• 存儲過程：6 個工具（create_procedure、modify_procedure、delete_procedure、list_procedures、describe_procedure、execute_procedure、get_procedure_parameters）
• 視圖：5 個工具（create_view、modify_view、delete_view、list_views、describe_view）
• 索引：4 個工具（create_index、delete_index、list_indexes、describe_index）
• 架構管理：2 個工具（list_schemas、list_all_objects）
• 總計：23 個工具 + 支持所有數據庫對象操作的增強型 write_query

💻 使用示例

理解 MCP 服務器

MCP（模型上下文協議）服務器旨在與 AI 助手和語言模型配合使用。它們通過標準輸入/輸出使用 JSON-RPC 協議進行通信，而不是作為傳統的 Web 服務。

可用工具（共 23 個）

增強型服務器提供了全面的數據庫管理工具：

核心數據庫操作（5 個工具）

1. read_query - 執行 SELECT 查詢以讀取數據
2. write_query - 執行 INSERT、UPDATE、DELETE 和 DDL 查詢
3. list_tables - 列出數據庫中的所有表
4. describe_table - 獲取特定表的架構信息
5. create_table - 創建新表

存儲過程管理（6 個工具）

6. create_procedure - 創建新的存儲過程
7. modify_procedure - 修改現有的存儲過程
8. delete_procedure - 刪除存儲過程
9. list_procedures - 列出所有帶有元數據的存儲過程
10. describe_procedure - 獲取完整的存儲過程定義
11. execute_procedure - 執行帶有參數的存儲過程
12. get_procedure_parameters - 獲取詳細的參數信息

視圖管理（5 個工具）

13. create_view - 創建新視圖
14. modify_view - 修改現有視圖
15. delete_view - 刪除視圖
16. list_views - 列出數據庫中的所有視圖
17. describe_view - 獲取視圖定義和架構

索引管理（4 個工具）

18. create_index - 創建新索引
19. delete_index - 刪除索引
20. list_indexes - 列出所有索引（可按表篩選）
21. describe_index - 獲取詳細的索引信息

架構探索（2 個工具）

22. list_schemas - 列出數據庫中的所有架構
23. list_all_objects - 按架構列出所有數據庫對象

可用資源

表和視圖都作為 MCP 資源公開，其 URI 如下：

• mssql://table_name/data - 以 CSV 格式訪問表數據
• mssql://view_name/data - 以 CSV 格式訪問視圖數據 資源以 CSV 格式提供前 100 行數據，以便快速進行數據探索。

數據庫架構遍歷示例

1. 探索數據庫結構

# 從架構開始
list_schemas

# 獲取特定架構中的所有對象
list_all_objects(schema_name: "dbo")

# 或者獲取所有架構中的所有對象
list_all_objects()

2. 表探索

# 列出所有表
list_tables

# 獲取詳細的表信息
describe_table(table_name: "YourTableName")

# 將表數據作為 MCP 資源訪問
# URI: mssql://YourTableName/data

3. 視圖管理

# 列出所有視圖
list_views

# 獲取視圖定義
describe_view(view_name: "YourViewName")

# 創建新視圖
create_view(view_script: "CREATE VIEW MyView AS SELECT * FROM MyTable WHERE Active = 1")

# 將視圖數據作為 MCP 資源訪問
# URI: mssql://YourViewName/data

4. 存儲過程操作

# 列出所有存儲過程
list_procedures

# 獲取完整的存儲過程定義（處理大型存儲過程，如 wmPostPurchase）
describe_procedure(procedure_name: "YourProcedureName")

# 將大型存儲過程保存到文件進行分析
write_file(file_path: "procedure_name.sql", content: "procedure_definition")

# 獲取參數詳細信息
get_procedure_parameters(procedure_name: "YourProcedureName")

# 執行存儲過程
execute_procedure(procedure_name: "YourProcedureName", parameters: ["param1", "param2"])

5. 索引管理

# 列出所有索引
list_indexes()

# 列出特定表的索引
list_indexes(table_name: "YourTableName")

# 獲取索引詳細信息
describe_index(index_name: "IX_YourIndex", table_name: "YourTableName")

# 創建新索引
create_index(index_script: "CREATE INDEX IX_NewIndex ON MyTable (Column1, Column2)")

存儲過程管理示例

創建簡單存儲過程

CREATE PROCEDURE GetEmployeeCount
AS
BEGIN
    SELECT COUNT(*) AS TotalEmployees FROM Employees
END

創建帶參數的存儲過程

CREATE PROCEDURE GetEmployeesByDepartment
    @DepartmentId INT,
    @MinSalary DECIMAL(10,2) = 0
AS
BEGIN
    SELECT 
        EmployeeId,
        FirstName,
        LastName,
        Salary,
        DepartmentId
    FROM Employees 
    WHERE DepartmentId = @DepartmentId 
    AND Salary >= @MinSalary
    ORDER BY LastName, FirstName
END

創建帶輸出參數的存儲過程

CREATE PROCEDURE GetDepartmentStats
    @DepartmentId INT,
    @EmployeeCount INT OUTPUT,
    @AverageSalary DECIMAL(10,2) OUTPUT
AS
BEGIN
    SELECT 
        @EmployeeCount = COUNT(*),
        @AverageSalary = AVG(Salary)
    FROM Employees 
    WHERE DepartmentId = @DepartmentId
END

修改現有存儲過程

ALTER PROCEDURE GetEmployeesByDepartment
    @DepartmentId INT,
    @MinSalary DECIMAL(10,2) = 0,
    @MaxSalary DECIMAL(10,2) = 999999.99
AS
BEGIN
    SELECT 
        EmployeeId,
        FirstName,
        LastName,
        Salary,
        DepartmentId,
        HireDate
    FROM Employees 
    WHERE DepartmentId = @DepartmentId 
    AND Salary BETWEEN @MinSalary AND @MaxSalary
    ORDER BY Salary DESC, LastName, FirstName
END

大內容處理

工作原理

服務器能夠高效處理大型數據庫對象，如存儲過程：

1. 直接檢索：直接從 SQL Server 中獲取完整內容
2. 無截斷：無論大小，返回完整的存儲過程定義
3. 聊天顯示：大型存儲過程可以在聊天界面中完整查看
4. 內存高效：通過數據庫連接流處理內容

使用示例

# 描述大型存儲過程（獲取完整定義）
describe_procedure(procedure_name: "wmPostPurchase")

# 適用於任何大小的存儲過程（已測試 1400 多行的存儲過程）
# 內容顯示在聊天中，以便查看和複製粘貼操作

文件操作限制

⚠️ 重要提示：雖然大型存儲過程可以在聊天中檢索和顯示，但由於推理令牌限制，通過 MCP 工具將其保存到文件中不可靠。對於批量數據提取：

1. 小型存儲過程：從聊天界面複製粘貼
2. 大型存儲過程：使用直接連接數據庫的獨立 Python 腳本
3. 批量操作：在 MCP 上下文之外創建專用的提取腳本

與 AI 助手集成

Claude Desktop

將此服務器添加到你的 Claude Desktop 配置中：

{
  "mcpServers": {
    "mssql": {
      "command": "python3",
      "args": ["/path/to/mcp-sqlserver/src/server.py"],
      "cwd": "/path/to/mcp-sqlserver",
      "env": {
        "MSSQL_SERVER": "your-server",
        "MSSQL_DATABASE": "your-database",
        "MSSQL_USER": "your-username",
        "MSSQL_PASSWORD": "your-password"
      }
    }
  }
}

其他 MCP 客戶端

服務器遵循標準 MCP 協議，應能與任何兼容的 MCP 客戶端配合使用。

🔧 技術細節

項目結構

mcp-sqlserver/
├── src/
│   └── server.py          # 帶有分塊系統的主要 MCP 服務器實現
├── tests/
│   └── test_server.py     # 單元測試
├── requirements.txt       # Python 依賴項
├── .env                   # 數據庫配置（從 env.example 創建）
├── env.example           # 配置模板
├── install.sh            # 安裝腳本
├── start.sh              # 服務器啟動腳本（用於開發）
├── stop.sh               # 服務器關閉腳本
├── status.sh             # 服務器狀態腳本
└── README.md             # 本文件

測試

運行測試套件：

python -m pytest tests/

測試數據庫連接：

python3 test_connection.py

日誌記錄

服務器使用 Python 的日誌記錄模塊。通過修改 src/server.py 中的 logging.basicConfig() 調用設置日誌級別。

安全性考慮

• 身份驗證：始終使用強密碼和安全的身份驗證方式
• 網絡：確保數據庫服務器得到適當的安全保護
• 權限：僅向用戶賬戶授予必要的數據庫權限
• SSL/TLS：儘可能使用加密連接
• 查詢驗證：服務器驗證查詢類型，防止未經授權的操作
• DDL 操作：對數據庫對象的創建/修改/刪除操作進行了適當的驗證
• 存儲過程執行：安全處理參數，防止注入攻擊
• 大內容處理：高效檢索大型存儲過程而不截斷
• 文件操作：寫入操作經過驗證並進行了沙盒處理
• 優先讀取原則：為了生產安全，探索工具默認設置為只讀

🛠️ 故障排除

常見問題

1. 連接失敗：檢查數據庫服務器地址、憑據和網絡連接
2. 未找到 ODBC 驅動：安裝 SQL Server 的 Microsoft ODBC 驅動 17
3. 權限被拒絕：確保數據庫用戶具有適當的權限
4. 端口問題：驗證正確的端口號和防火牆設置
5. 大內容問題：大型存儲過程可以在聊天中顯示，但無法通過 MCP 工具保存到文件中
6. 內存問題：大型內容通過數據庫連接高效流式傳輸

調試模式

通過在 src/server.py 中將日誌級別設置為 DEBUG 來啟用調試日誌記錄：

logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')

大內容故障排除

如果遇到大內容問題：

1. 複製粘貼方法：使用聊天界面查看和複製大型存儲過程
2. 外部腳本：創建獨立的 Python 腳本進行批量數據提取
3. 檢查內存：大型存儲過程由數據庫連接高效處理
4. 驗證權限：確保數據庫用戶可以訪問存儲過程定義
5. 使用較小的存儲過程進行測試：首先驗證基本功能

獲取幫助

1. 檢查服務器日誌以獲取詳細的錯誤消息
2. 驗證你的 .env 配置
3. 獨立測試數據庫連接
4. 確保所有依賴項都已正確安裝
5. 對於大內容問題，從聊天中複製粘貼或創建外部提取腳本

🆕 近期改進

大內容處理（最新）

• 驗證了大型存儲過程的完整檢索，無截斷
• 成功測試瞭如 wmPostPurchase 這樣的存儲過程（1400 多行，57KB）
• 大型存儲過程在聊天界面中完整顯示，便於查看和複製粘貼
• 通過數據庫連接流式傳輸實現高效的內存處理
• 注意：由於令牌限制，通過 MCP 工具進行文件操作對於大內容不可靠

完整的數據庫對象管理

• 從 5 個擴展到 23 個全面的數據庫管理工具
• 為所有主要數據庫對象添加了完整的 CRUD 操作
• 實現了與 SSMS 功能相匹配的架構遍歷功能
• 為表和視圖添加了 MCP 資源訪問
• 通過適當的操作驗證增強了安全性

📄 許可證

本項目為開源項目。有關詳細信息，請參閱許可證文件。

🤝 貢獻

歡迎貢獻代碼！請隨時提交拉取請求或提出關於錯誤和功能請求的問題。