Text To Sql MCP Server

🚀 文本到 SQL 的 MCP 服務器

本項目是一個基於 FastMCP 框架的安全數據庫查詢服務，可用於數據庫查詢與分析，為用戶提供安全、高效的數據庫操作體驗。

🚀 快速開始

本項目是一個 MCP (Model Context Protocol) 服務器，專門用於提供安全的數據庫查詢服務。它基於 FastMCP 框架構建，支持 MySQL 數據庫連接，並提供了完整的權限管理和安全控制機制。

✨ 主要特性

• 數據庫連接管理：實現安全的 MySQL 數據庫連接和查詢。
• 權限認證：採用基於 RSA 密鑰對的 Bearer Token 認證方式。
• 安全查詢：具備防止 SQL 注入和危險操作的安全檢查功能。
• 表結構查詢：可獲取數據庫表列表和表結構信息。
• SQL 執行：支持安全的 SQL 查詢執行，並支持結果限制。
• 健康檢查：能夠對服務狀態進行監控。
• 權限管理：提供細粒度的權限控制。

🛠️ 技術細節

• Python 3.x：作為主要編程語言。
• FastMCP：作為 MCP 服務器框架。
• MySQL：用作數據庫系統。
• uvicorn：作為 ASGI 服務器。
• python - dotenv：用於環境變量管理。

📦 安裝指南

安裝依賴

pip install -r requirements.txt

依賴包說明

python >=3.10

• fastmcp==2.10.6：MCP 服務器框架。
• python - dotenv==1.1.0：環境變量加載。
• mysql - connector - python==8.2.0：MySQL 數據庫連接器。
• uvicorn==0.24.0：ASGI 服務器。

⚙️ 配置

1. 環境變量配置

複製 .env.example 文件為 .env 並配置數據庫連接信息：

cp .env.example .env

編輯 .env 文件：

# 數據庫配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database

# 可選：服務器配置
MCP_HOST=127.0.0.1
MCP_PORT=8000

2. 數據庫初始化

使用提供的 dataset.sql 文件初始化示例數據：

mysql -u your_username -p your_database < dataset.sql

該文件包含了一個 contracts 表的示例數據，包含合同信息。

🚀 啟動服務

python mcp_server.py

服務啟動後會顯示：

Authorization=Bearer ...
🚀 啟動 MCP 數據查詢服務器...
📍 地址: http://127.0.0.1:8000
📋 可用工具:
   - health_check: 健康檢查
   - get_user_permissions: 獲取用戶權限
   - get_database_tables: 獲取數據庫表列表
   - get_table_structure: 獲取表結構
   - execute_sql_query: 執行 SQL 查詢
   - generate_sql_from_question: 自然語言生成 SQL
   - analyze_query_result: 查詢結果分析

MCP 客戶端配置


💻 使用示例

基礎用法

以下是啟動服務的命令示例：

python mcp_server.py

高級用法

在進行數據庫初始化時，使用 dataset.sql 文件初始化示例數據：

mysql -u your_username -p your_database < dataset.sql

🔧 API 文檔

1. 健康檢查

• 工具名：health_check
• 描述：檢查服務和數據庫連接狀態
• 權限：無需特殊權限

2. 獲取用戶權限

• 工具名：get_user_permissions
• 描述：獲取當前用戶的權限信息
• 權限：需要有效的訪問令牌

3. 獲取數據庫表列表

• 工具名：get_database_tables
• 描述：獲取數據庫中所有表的列表
• 權限：需要 data:read_tables 權限

4. 獲取表結構

• 工具名：get_table_structure
• 參數：
  • table_name (string)：表名
• 描述：獲取指定表的結構信息、行數和樣本數據
• 權限：需要 data:read_tables 權限

5. 執行 SQL 查詢

• 工具名：execute_sql_query
• 參數：
  • sql_query (string)：SQL 查詢語句
  • limit (int, 可選)：返回結果的最大行數，默認 100
• 描述：安全執行 SQL 查詢
• 權限：需要 data:read_table_data 權限
• 安全限制：禁止執行 DROP、DELETE、UPDATE、INSERT 等修改操作

🔐 安全特性

權限系統

• 基於 RSA 密鑰對的 JWT Token 認證
• 細粒度權限控制：
  • data:read_tables：讀取表結構權限
  • data:read_table_data：讀取表數據權限

安全檢查

• SQL 注入防護：禁止危險的 SQL 操作
• 查詢限制：自動添加 LIMIT 限制，防止大量數據查詢
• 敏感數據保護：對包含敏感關鍵詞的查詢進行額外權限檢查

📁 項目結構

text - to - sql - mcp/
├── mcp_server.py          # 主服務器文件
├── database.py            # 數據庫管理模塊
├── auth_token.py          # 認證令牌生成模塊
├── requirements.txt       # 項目依賴
├── .env.example          # 環境變量示例
├── dataset.sql           # 示例數據庫結構和數據
└── README.md             # 項目文檔

🔍 技術細節

mcp_server.py

主服務器文件，包含：

• MCP 服務器初始化
• 所有 API 工具的定義
• 權限驗證邏輯
• 安全檢查機制

database.py

數據庫管理模塊，提供：

• MySQL 數據庫連接管理
• SQL 查詢執行
• 表結構信息獲取
• 數據類型轉換

auth_token.py

認證模塊，負責：

• RSA 密鑰對生成
• JWT 訪問令牌創建
• 認證提供者配置

🚨 注意事項

⚠️ 重要提示

1. 確保數據庫用戶權限最小化，只授予必要的查詢權限，保障數據庫安全。
2. 生產環境建議使用 HTTPS 和防火牆保護，確保網絡安全。
3. 定期更新訪問令牌，避免長期使用同一令牌，加強令牌管理。
4. 監控查詢性能，避免複雜查詢影響數據庫性能。

🤝 貢獻

歡迎提交 Issue 和 Pull Request 來改進這個項目。

我的作品

n8n 工作流自動化模版站，收集了大量可直接使用的自動化流程：https://n8ntemplates.dev