Text-to-SQL MCP 数据查询服务器
一个基于 FastMCP 框架的安全数据库查询 MCP 服务，用于数据库查询和分析。
🚀 项目简介
本项目是一个 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客户端配置
🔧 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 访问令牌创建
- 认证提供者配置
🚨 注意事项
- 数据库安全: 确保数据库用户权限最小化，只授予必要的查询权限
- 网络安全: 生产环境建议使用 HTTPS 和防火墙保护
- 令牌管理: 定期更新访问令牌，避免长期使用同一令牌
- 查询监控: 监控查询性能，避免复杂查询影响数据库性能
🤝 贡献
欢迎提交 Issue 和 Pull Request 来改进这个项目。
我的作品
n8n 工作流自动化模版站，收集了大量可直接使用的自动化流程：https://n8ntemplates.dev
