MySQL查询服务器 / MySQL Query Server

1. 项目简介 / Project Introduction

本项目是基于MCP框架开发的MySQL查询服务器，支持通过SSE协议实现实时数据库操作。系统具备完善的安全防护、日志记录、配置管理和敏感信息保护功能，可满足开发、测试及生产环境下的安全MySQL数据访问需求。

This project is a MySQL query server built on the MCP framework, which supports real-time database operations through the SSE protocol. It provides comprehensive security protection, logging, configuration management, and sensitive information protection mechanisms, making it suitable for secure MySQL data access in development, testing, and production environments.

2. 主要特性 / Key Features

基于FastMCP框架构建，采用异步高性能架构
支持高并发场景的数据库连接池，参数可灵活配置
内置SSE实时数据推送功能
提供丰富的MySQL元数据与结构查询API接口
自动化事务管理与回滚机制
多层级SQL风险控制与注入防护体系
敏感信息自动隐藏及自定义屏蔽功能
灵活的环境变量配置方案
完善的日志记录与错误处理机制
支持Docker容器化部署，实现快速上线
Built on FastMCP framework with high-performance async architecture
Connection pool designed for high concurrency with flexible parameter tuning
SSE real-time data push capability
Comprehensive MySQL metadata and schema query APIs
Automated transaction management and rollback
Multi-level SQL risk control and injection protection
Automatic and customizable sensitive information masking
Flexible environment variable configuration
Robust logging and error handling
Docker support for rapid deployment

3. 快速开始 / Quick Start

Docker部署方式 / Docker Method

# 拉取镜像
docker pull mangooer/mysql-mcp-server-sse:latest

# 运行容器
docker run -d \
  --name mysql-mcp-server-sse \
  -e HOST=0.0.0.0 \
  -e PORT=3000 \
  -e MYSQL_HOST=your_mysql_host \
  -e MYSQL_PORT=3306 \
  -e MYSQL_USER=your_mysql_user \
  -e MYSQL_PASSWORD=your_mysql_password \
  -e MYSQL_DATABASE=your_database \
  -p 3000:3000 \
  mangooer/mysql-mcp-server-sse:latest

Windows PowerShell格式：

docker run -d `
  --name mysql-mcp-server-sse `
  -e HOST=0.0.0.0 `
  -e PORT=3000 `
  -e MYSQL_HOST=your_mysql_host `
  -e MYSQL_PORT=3306 `
  -e MYSQL_USER=your_mysql_user `
  -e MYSQL_PASSWORD=your_mysql_password `
  -e MYSQL_DATABASE=your_database `
  -p 3000:3000 `
  mangooer/mysql-mcp-server-sse:latest

源码部署方式 / Source Code Method

安装依赖 / Install Dependencies

pip install -r requirements.txt

配置环境变量 / Configure Environment Variables

将.env.example文件复制为.env，并根据实际环境修改配置。
Copy .env.example to .env and modify as needed.

启动服务 / Start the Server

python -m src.server

默认访问地址：http://127.0.0.1:3000/sse
Default endpoint: http://127.0.0.1:3000/sse

4. 目录结构 / Project Structure

.
├── src/
│   ├── server.py           # 主服务器入口文件 / Main server entry
│   ├── config.py           # 配置项定义文件 / Config definitions
│   ├── validators.py       # 参数校验模块 / Parameter validation
│   ├── db/
│   │   └── mysql_operations.py # 数据库操作模块 / DB operations
│   ├── security/
│   │   ├── interceptor.py      # SQL拦截模块 / SQL interception
│   │   ├── query_limiter.py    # 风险控制模块 / Risk control
│   │   └── sql_analyzer.py     # SQL分析模块 / SQL analysis
│   └── tools/
│       ├── mysql_tool.py           # 基础查询工具 / Basic query
│       ├── mysql_metadata_tool.py  # 元数据查询工具 / Metadata query
│       ├── mysql_info_tool.py      # 信息查询工具 / Info query
│       ├── mysql_schema_tool.py    # 结构查询工具 / Schema query
│       └── metadata_base_tool.py   # 工具基类 / Tool base class
├── tests/                  # 测试模块 / Tests
├── .env.example            # 环境变量示例文件 / Env example
└── requirements.txt        # 项目依赖清单 / Requirements

5. 环境变量与配置 / Environment Variables & Configuration

变量名 / Variable	说明 / Description	默认值 / Default
HOST	服务器监听地址 / Server listen address	127.0.0.1
PORT	服务器监听端口 / Server listen port	3000
MYSQL_HOST	MySQL服务器地址 / MySQL server host	localhost
MYSQL_PORT	MySQL服务器端口 / MySQL server port	3306
MYSQL_USER	MySQL用户名 / MySQL username	root
MYSQL_PASSWORD	MySQL密码 / MySQL password	(空/empty)
MYSQL_DATABASE	要连接的数据库名 / Database name	(空/empty)
DB_CONNECTION_TIMEOUT	连接超时时间(秒) / Connection timeout (seconds)	5
DB_AUTH_PLUGIN	认证插件类型 / Auth plugin type	mysql_native_password
DB_POOL_ENABLED	是否启用连接池 / Enable connection pool (true/false)	true
DB_POOL_MIN_SIZE	连接池最小连接数 / Pool min size	5
DB_POOL_MAX_SIZE	连接池最大连接数 / Pool max size	20
DB_POOL_RECYCLE	连接回收时间(秒) / Pool recycle time (seconds)	300
DB_POOL_MAX_LIFETIME	连接最大存活时间(秒, 0=不限制) / Max lifetime (sec)	0
DB_POOL_ACQUIRE_TIMEOUT	获取连接超时时间(秒) / Acquire timeout (seconds)	10.0
ENV_TYPE	环境类型(development/production) / Env type	development
ALLOWED_RISK_LEVELS	允许的风险等级(逗号分隔) / Allowed risk levels	LOW,MEDIUM
ALLOW_SENSITIVE_INFO	允许查询敏感字段 / Allow sensitive info (true/false)	false
SENSITIVE_INFO_FIELDS	自定义敏感字段模式(逗号分隔) / Custom sensitive fields	(空/empty)
MAX_SQL_LENGTH	最大SQL语句长度 / Max SQL length	5000
BLOCKED_PATTERNS	阻止的SQL模式(逗号分隔) / Blocked SQL patterns	(空/empty)
ENABLE_QUERY_CHECK	启用查询安全检查 / Enable query check (true/false)	true
LOG_LEVEL	日志级别(DEBUG/INFO/...) / Log level	DEBUG

注意/Note: 部分云MySQL服务需要将DB_AUTH_PLUGIN设置为mysql_native_password。

6. 自动化与资源管理优化 / Automation & Resource Management Enhancements

自动化工具注册 / Automated Tool Registration

所有MySQL相关API工具均采用自动注册机制：
- 无需手动在主入口维护注册代码，新增/删除工具只需在src/tools/目录下实现register_xxx_tool(s)函数即可。
- 系统启动时自动扫描并注册，极大提升可维护性和扩展性。
All MySQL-related API tools are registered automatically:
- No need to manually maintain registration code in the main entry. To add or remove a tool, simply implement a register_xxx_tool(s) function in the src/tools/ directory.
- The system scans and registers tools automatically at startup, greatly improving maintainability and extensibility.

连接池自动回收与资源管理 / Connection Pool Auto-Recycling & Resource Management

连接池采用事件循环隔离与自动回收机制：
- 每个事件循环独立池，支持高并发与多环境。
- 定期（默认每5分钟）自动回收无效或失效的连接池，防止资源泄漏。
- 事件循环关闭时自动关闭对应连接池，确保资源彻底释放。
- 支持多数据库/多租户场景扩展。
所有资源管理操作均有详细日志，便于追踪和排查。
The connection pool uses event loop isolation and auto-recycling:
- Each event loop has its own pool, supporting high concurrency and multi-environment deployment.
- Unused or invalid pools are automatically recycled every 5 minutes (by default), preventing resource leaks.
- When an event loop is closed, its pool is automatically closed to ensure complete resource release.
- Ready for multi-database/multi-tenant scenarios.
All resource management operations are logged in detail for easy tracking and troubleshooting.

7. 安全机制 / Security Mechanisms

多级SQL风险等级（LOW/MEDIUM/HIGH/CRITICAL）
SQL注入与危险操作拦截
WHERE子句强制检查
敏感信息自动隐藏（支持自定义字段）
生产环境默认只允许低风险操作
Multi-level SQL risk levels (LOW/MEDIUM/HIGH/CRITICAL)
SQL injection & dangerous operation interception
Mandatory WHERE clause check
Automatic sensitive info masking (customizable fields)
Production allows only low-risk operations by default

8. 日志与错误处理 / Logging & Error Handling

日志级别可配置（LOG_LEVEL）
控制台与文件日志输出
详细记录运行状态与错误
完善的异常捕获与事务回滚
Configurable log level (LOG_LEVEL)
Console & file log output
Detailed running status & error logs
Robust exception capture & transaction rollback

9. 常见问题 / FAQ

Q: DELETE操作未执行成功？

A: 检查是否有WHERE条件，无WHERE为高风险，需在ALLOWED_RISK_LEVELS中允许CRITICAL。

Q: Why does DELETE not work?
A: Check for WHERE clause. DELETE without WHERE is high risk (CRITICAL), must be allowed in ALLOWED_RISK_LEVELS.

Q: 如何自定义敏感字段？

A: 设置SENSITIVE_INFO_FIELDS，如SENSITIVE_INFO_FIELDS=password,token

Q: How to customize sensitive fields?
A: Set SENSITIVE_INFO_FIELDS, e.g. SENSITIVE_INFO_FIELDS=password,token

Q: limit参数报错？

A: limit必须为非负整数。

Q: limit parameter error?
A: limit must be a non-negative integer.

10. 贡献指南 / Contribution Guide

欢迎通过Issue和Pull Request参与改进。
Contributions via Issue and Pull Request are welcome.

11. 许可证 / License

MIT License

本软件按"原样"提供，不提供任何形式的明示或暗示的保证，包括但不限于对适销性、特定用途的适用性和非侵权性的保证。在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论是在合同诉讼、侵权行为还是其他方面，产生于、源于或与本软件有关，或与本软件的使用或其他交易有关。
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.