Universal Sql MCP Server

🚀 通用 SQL MCP 服務器

通用 SQL MCP 服務器是一個模型上下文協議（MCP）服務器，它為多個 SQL 數據庫引擎提供安全訪問。該服務器使 AI 助手和其他 MCP 客戶端能夠通過標準化接口與各種 SQL 數據庫進行交互。

🚀 快速開始

嘗試演示（SQLite）

查看通用 SQL MCP 服務器實際運行效果的最快方法：

# 克隆倉庫
git clone <repository-url>
cd gen-http-sql-mcp

# 安裝依賴
pip install fastmcp mysql-connector-python psycopg2-binary pyodbc sqlalchemy python-dotenv

# 運行演示（創建一個包含示例數據的 SQLite 數據庫）
python demo.py

# 啟動 MCP 服務器
python main.py

該演示會創建一個包含示例用戶和訂單的 SQLite 數據庫，然後展示所有 MCP 工具的使用。

✨ 主要特性

• 多數據庫支持：支持 MySQL、PostgreSQL、SQLite 和 SQL Server。
• 數據庫模式檢查：獲取所有表、列、索引和約束的全面信息。
• 安全查詢執行：通過內置的安全限制執行 SELECT 查詢。
• 受控寫操作：通過適當的安全控制執行 INSERT 和 UPDATE 操作。
• 連接測試：驗證數據庫連接和配置。
• 基於環境的配置：通過環境變量進行安全配置。
• 全面日誌記錄：提供詳細的日誌，用於監控和調試。
• 數據庫特定優化：為每個數據庫引擎提供定製的查詢和功能。

📦 安裝指南

1. 克隆此倉庫：

git clone <repository-url>
cd gen-http-sql-mcp

2. 安裝依賴：

# 使用 pip
pip install fastmcp mysql-connector-python psycopg2-binary pyodbc sqlalchemy python-dotenv

# 或者使用 uv
uv sync

3. 可選：僅在需要時安裝特定於數據庫的驅動程序：

# 僅適用於 MySQL
pip install fastmcp mysql-connector-python python-dotenv

# 僅適用於 PostgreSQL
pip install fastmcp psycopg2-binary python-dotenv

# 僅適用於 SQLite（無需額外驅動程序）
pip install fastmcp python-dotenv

# 僅適用於 SQL Server
pip install fastmcp pyodbc python-dotenv

💻 使用示例

運行服務器

啟動 MCP 服務器：

uv run python main.py

服務器將執行以下操作：

1. 從環境變量加載配置。
2. 測試數據庫連接。
3. 啟動 MCP 服務器並監聽請求。

與 MCP 客戶端一起使用

此服務器實現了模型上下文協議，可與任何兼容 MCP 的客戶端一起使用。服務器提供了三個可供 MCP 客戶端調用的工具。

工具調用示例

1. 獲取數據庫模式：

{
  "method": "tools/call",
  "params": {
    "name": "get_database_schema"
  }
}

2. 執行 SQL 查詢（適用於所有數據庫類型）：

{
  "method": "tools/call",
  "params": {
    "name": "execute_sql_query",
    "arguments": {
      "sql_query": "SELECT * FROM users LIMIT 10"
    }
  }
}

3. 執行寫操作（適用於所有數據庫類型）：

{
  "method": "tools/call",
  "params": {
    "name": "execute_write_operation",
    "arguments": {
      "sql_query": "INSERT INTO users (name, email) VALUES ('John Doe', 'john@example.com')"
    }
  }
}

特定數據庫的查詢示例

帶有 RETURNING 子句的 PostgreSQL：

INSERT INTO users (name, email) VALUES ('Jane Doe', 'jane@example.com') RETURNING id;

帶有自增功能的 SQLite：

INSERT INTO users (name, email) VALUES ('Bob Smith', 'bob@example.com');

帶有 OUTPUT 子句的 SQL Server：

INSERT INTO users (name, email) OUTPUT INSERTED.id VALUES ('Alice Johnson', 'alice@example.com');

4. 測試連接：

{
  "method": "tools/call",
  "params": {
    "name": "test_database_connection"
  }
}

📚 詳細文檔

配置

1. 複製示例環境文件：

cp .env.example .env

2. 使用你的數據庫憑據編輯 .env 文件：

MySQL 配置

DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database

PostgreSQL 配置

DB_TYPE=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database

SQLite 配置

DB_TYPE=sqlite
DB_NAME=/path/to/your/database.db
# 注意：SQLite 不需要主機、端口、用戶或密碼

SQL Server 配置

DB_TYPE=sqlserver
DB_HOST=localhost
DB_PORT=1433
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database
DB_DRIVER=ODBC Driver 17 for SQL Server

常見可選設置

# 可選：連接池設置（不適用於 SQLite）
DB_POOL_SIZE=5
DB_MAX_OVERFLOW=10

# 可選：連接超時設置（以秒為單位）
DB_CONNECT_TIMEOUT=10
DB_READ_TIMEOUT=30
DB_WRITE_TIMEOUT=30

# 可選：啟用寫操作（INSERT/UPDATE） - 設置為 true 以啟用
ENABLE_WRITE_OPERATIONS=false

配置選項

• DB_TYPE：指定要使用的數據庫引擎
  • mysql：MySQL 數據庫（需要 mysql-connector-python）
  • postgresql：PostgreSQL 數據庫（需要 psycopg2-binary）
  • sqlite：SQLite 數據庫（Python 內置支持）
  • sqlserver：SQL Server 數據庫（需要 pyodbc）
• ENABLE_WRITE_OPERATIONS：控制 execute_write_operation 工具是否可用
  • false（默認）：僅允許只讀操作（僅 SELECT 查詢）
  • true：通過 execute_write_operation 工具啟用 INSERT 和 UPDATE 操作
  • 出於安全原因，DELETE、DROP、TRUNCATE、ALTER 和 CREATE 操作始終被阻止
• 請求日誌記錄配置：
  • ENABLE_REQUEST_LOGGING：啟用基本請求日誌記錄（默認值為 true）
  • ENABLE_DETAILED_REQUEST_LOGGING：啟用帶有標頭和有效負載的詳細請求日誌記錄（默認值為 false）
  • REQUEST_LOG_LEVEL：請求日誌記錄的日誌級別（默認值為 INFO）
  • MAX_PAYLOAD_LOG_LENGTH：記錄的有效負載的最大長度（默認值為 2000）
  • LOG_LEVEL：通用應用程序日誌級別（默認值為 INFO）

特定數據庫注意事項

• SQLite：僅需要 DB_NAME（文件路徑）。連接池設置將被忽略。
• SQL Server：可能需要額外安裝 ODBC 驅動程序並指定 DB_DRIVER。
• PostgreSQL：使用 psycopg2-binary 以獲得最佳性能和兼容性。
• MySQL：使用官方的 mysql-connector-python 驅動程序。

🔧 技術細節

安全特性

• 受控寫訪問：寫操作僅允許 INSERT 和 UPDATE 操作。
• 讀訪問：通過專用工具提供 SELECT 查詢。
• 查詢驗證：阻止危險的 SQL 關鍵字（DELETE、DROP、TRUNCATE 等）。
• 操作分離：讀和寫操作由單獨的工具處理。
• 環境變量：敏感配置存儲在環境變量中。
• 連接管理：通過超時和清理進行適當的連接處理。
• 事務安全：寫操作包括自動提交和錯誤處理。

項目結構

gen-http-sql-mcp/
├── main.py              # 主服務器入口點
├── database.py          # 通用數據庫連接和管理
├── tools.py             # MCP 工具實現
├── .env.example         # 環境配置模板
├── pyproject.toml       # 項目依賴項和元數據
└── README.md           # 此文件

數據庫引擎支持詳情

MySQL

• 支持完整的模式內省，包括表註釋、列詳細信息和索引信息。
• 支持連接池和超時配置。
• 使用 mysql-connector-python 以獲得最佳兼容性。

PostgreSQL

• 提供全面的模式信息，包括表和列註釋。
• 提供高級索引信息和約束詳細信息。
• 使用 psycopg2-binary 以實現高性能。

SQLite

• 提供完整的表和列信息。
• 提供索引詳細信息和主鍵信息。
• 非常適合開發、測試和輕量級應用程序。
• 無需額外安裝驅動程序。

SQL Server

• 提供完整的表和列模式信息。
• 支持 Windows 和 SQL Server 身份驗證。
• 通過 pyodbc 使用 ODBC 連接。
• 可配置 ODBC 驅動程序選擇。

依賴項

• fastmcp：用於構建 MCP 服務器的 FastMCP 框架。
• mysql-connector-python：Python 的官方 MySQL 驅動程序。
• psycopg2-binary：Python 的 PostgreSQL 適配器。
• pyodbc：用於 SQL Server 的 ODBC 數據庫連接。
• sqlalchemy：SQL 工具包和對象關係映射庫。
• python-dotenv：環境變量加載。
• sqlite3：Python 內置的 SQLite 支持（無需額外安裝）。

錯誤處理

服務器包含全面的錯誤處理：

• 記錄並報告數據庫連接錯誤。
• 以清晰的錯誤消息拒絕無效的 SQL 查詢。
• 配置驗證確保所需參數存在。
• 在中斷時優雅關閉。

日誌記錄

服務器提供全面的日誌記錄功能：

基本日誌記錄

• 連接狀態和數據庫信息。
• 查詢執行結果和性能。
• 帶有上下文的錯誤消息。
• 服務器啟動和關閉事件。

請求日誌記錄

服務器包含高級請求日誌記錄中間件，以幫助調試客戶端連接問題：

簡單請求日誌記錄（默認）

# 默認啟用，顯示基本請求信息
ENABLE_REQUEST_LOGGING=true

詳細請求日誌記錄（調試模式）

# 啟用帶有標頭和有效負載的詳細日誌記錄
ENABLE_DETAILED_REQUEST_LOGGING=true
REQUEST_LOG_LEVEL=DEBUG
MAX_PAYLOAD_LOG_LENGTH=5000
LOG_LEVEL=DEBUG

Docker 調試環境

要調試客戶端連接問題，請使用調試環境：

# 啟動帶有詳細日誌記錄的調試環境
make debug

# 查看調試日誌
make logs-debug

# 僅查看 MCP 服務器的調試日誌
make logs-debug-mcp

調試環境啟用以下功能：

• 詳細的請求/響應日誌記錄。
• HTTP 標頭日誌記錄。
• 請求有效負載日誌記錄。
• 響應有效負載日誌記錄。
• 執行計時。
• 客戶端信息跟蹤。

📄 許可證

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

支持

若遇到問題或有疑問，請按以下步驟操作：

1. 檢查日誌以獲取錯誤消息。
2. 驗證你的數據庫配置。
3. 確保你的數據庫服務器可訪問。
4. 在倉庫中創建一個問題。