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