MySQL查询服务器 / MySQL Query Server

MySQL 查询服务器 / MySQL Query Server

---

1. 项目简介 / 项目简介

本项目是基于 MCP 框架的 MySQL 查询服务器，支持通过 SSE 协议进行实时数据库操作。它具备完善的安全、日志、配置和敏感信息保护机制，适用于开发、测试和生产环境下的安全 MySQL 数据访问。

---

2. 主要特性 / 主要特性

• 基于 FastMCP 框架，异步高性能
• 支持高并发的数据库连接池，参数灵活可调
• 支持 SSE 实时推送
• 提供丰富的 MySQL 元数据与结构查询 API
• 自动事务管理与回滚
• 多级 SQL 风险控制与注入防护
• 数据库隔离安全：防止跨数据库访问，支持三级访问控制
• 自动隐藏敏感信息，支持自定义
• 灵活的环境变量配置
• 完善的日志与错误处理
• 支持 Docker，快速部署

---

3. 快速开始 / 快速开始

Docker 方式 / Docker 方式

# 拉取镜像
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

源码方式 / 源码方式

安装依赖 / 安装依赖

pip install -r requirements.txt

配置环境变量 / 配置环境变量

将 .env.example 复制为 .env，并根据实际情况修改。

启动服务 / 启动服务

python -m src.server

默认监听地址：http://127.0.0.1:3000/sse

---

4. 目录结构 / 目录结构

.
├── 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. 环境变量与配置 / 环境变量与配置

变量名 / 变量	说明 / 说明	默认值 / 默认值
HOST	服务器监听地址 / 服务器监听地址	127.0.0.1
PORT	服务器监听端口 / 服务器监听端口	3000
MYSQL_HOST	MySQL服务器地址 / MySQL 服务主机	localhost
MYSQL_PORT	MySQL服务器端口 / MySQL 服务端口	3306
MYSQL_USER	MySQL用户名 / MySQL 用户名	root
MYSQL_PASSWORD	MySQL密码 / MySQL 密码	(空/空)
MYSQL_DATABASE	要连接的数据库名 / 数据库名称	(空/空)
DB_CONNECTION_TIMEOUT	连接超时时间(秒) / 连接超时时间（秒）	5
DB_AUTH_PLUGIN	认证插件类型 / 认证插件类型	mysql_native_password
DB_POOL_ENABLED	是否启用连接池 / 启用连接池（true/false）	true
DB_POOL_MIN_SIZE	连接池最小连接数 / 连接池最小连接数	5
DB_POOL_MAX_SIZE	连接池最大连接数 / 连接池最大连接数	20
DB_POOL_RECYCLE	连接回收时间(秒) / 连接池回收时间（秒）	300
DB_POOL_MAX_LIFETIME	连接最大存活时间(秒, 0=不限制) / 最大存活时间（秒）	0
DB_POOL_ACQUIRE_TIMEOUT	获取连接超时时间(秒) / 获取连接超时时间（秒）	10.0
ENV_TYPE	环境类型(development/production) / 环境类型	development
ALLOWED_RISK_LEVELS	允许的风险等级(逗号分隔) / 允许的风险等级	LOW,MEDIUM
ALLOW_SENSITIVE_INFO	允许查询敏感字段 / 允许查询敏感信息（true/false）	false
SENSITIVE_INFO_FIELDS	自定义敏感字段模式(逗号分隔) / 自定义敏感字段	(空/空)
MAX_SQL_LENGTH	最大SQL语句长度 / 最大 SQL 长度	5000
BLOCKED_PATTERNS	阻止的SQL模式(逗号分隔) / 被阻止的 SQL 模式	(空/空)
ENABLE_QUERY_CHECK	启用查询安全检查 / 启用查询检查（true/false）	true
ENABLE_DATABASE_ISOLATION	启用数据库隔离 / 启用数据库隔离（true/false）	false
DATABASE_ACCESS_LEVEL	数据库访问级别 / 数据库访问级别（strict/restricted/permissive）	permissive
LOG_LEVEL	日志级别(DEBUG/INFO/...) / 日志级别	DEBUG

注/注：部分云MySQL需指定DB_AUTH_PLUGIN为mysql_native_password。

MySQL 8.0 认证支持 / MySQL 8.0 认证支持

本系统完全支持 MySQL 8.0 的认证机制。MySQL 8.0 默认使用 caching_sha2_password 认证插件，提供更高的安全性。

本系统完全支持 MySQL 8.0 认证机制。MySQL 8.0 默认使用 caching_sha2_password，以增强安全性。

认证插件对比 / 认证插件对比

认证插件 / 插件	安全性 / 安全性	兼容性 / 兼容性	依赖要求 / 依赖项
mysql_native_password	中等 / 中等	高 / 高	无 / 无
caching_sha2_password	高 / 高	中等 / 中等	cryptography

配置建议 / 配置建议

生产环境 / 生产环境（推荐 / 推荐）：

DB_AUTH_PLUGIN=caching_sha2_password

开发环境 / 开发环境（简化配置 / 简化配置）：

DB_AUTH_PLUGIN=mysql_native_password

依赖安装 / 依赖安装

使用 caching_sha2_password 时需要安装 cryptography 包（已包含在 requirements.txt 中）：

使用 caching_sha2_password 时需要安装 cryptography 包（已包含在 requirements.txt 中）：

pip install cryptography

数据库隔离安全 / 数据库隔离安全

本系统提供强大的数据库隔离功能，防止跨数据库访问，确保数据安全。

本系统提供强大的数据库隔离功能，可防止跨数据库访问并确保数据安全。

访问级别

级别	允许访问	适用场景
strict	仅指定数据库	生产环境
restricted	指定数据库 + 系统数据库	开发环境
permissive	所有数据库	测试环境

启用数据库隔离

# Docker 启用严格模式 / Docker with strict mode
docker run -d \
  -e MYSQL_DATABASE=your_database \
  -e ENABLE_DATABASE_ISOLATION=true \
  -e DATABASE_ACCESS_LEVEL=strict \
  mangooer/mysql-mcp-server-sse:latest

# 生产环境自动启用 / Auto-enable in production
docker run -d \
  -e ENV_TYPE=production \
  -e MYSQL_DATABASE=your_database \
  mangooer/mysql-mcp-server-sse:latest

安全效果：

• ✅ 阻止 SHOW DATABASES
• ✅ 阻止 SELECT * FROM mysql.user
• ✅ 阻止 SHOW TABLES FROM other_db
• ✅ 允许当前数据库操作

🔒 重要：生产环境（ENV_TYPE=production）会自动启用数据库隔离，并采用 restricted 模式。

🔒 重要：生产环境（ENV_TYPE=production）会自动启用数据库隔离，并采用 restricted 模式。

---

6. 自动化与资源管理优化

自动化工具注册

• 所有 MySQL 相关 API 工具均采用自动注册机制：
  • 无需在主入口手动维护注册代码；添加或删除工具只需在 src/tools/ 目录下实现 register_xxx_tool(s) 函数即可。
  • 系统启动时会自动扫描并注册工具，大幅提升可维护性和可扩展性。
• 所有 MySQL 相关 API 工具均会自动注册：
  • 无需在主入口手动维护注册代码；添加或删除工具时，只需在 src/tools/ 目录下实现 register_xxx_tool(s) 函数即可。
  • 系统启动时会自动扫描并注册工具，大幅提升可维护性和可扩展性。

连接池自动回收与资源管理

• 连接池采用事件循环隔离与自动回收机制：
  • 每个事件循环都有独立的连接池，支持高并发和多环境部署。
  • 定期（默认每 5 分钟）自动回收未使用或失效的连接池，防止资源泄漏。
  • 事件循环关闭时，会自动关闭对应的连接池，确保彻底释放资源。
  • 可扩展以支持多数据库 / 多租户场景。
• 所有资源管理操作均有详细日志，便于跟踪和排查。
• 连接池采用事件循环隔离与自动回收机制：
  • 每个事件循环都有独立的连接池，支持高并发和多环境部署。
  • 定期（默认每 5 分钟）自动回收未使用或失效的连接池，防止资源泄漏。
  • 事件循环关闭时，会自动关闭对应的连接池，确保彻底释放资源。
  • 可扩展以支持多数据库 / 多租户场景。
• 所有资源管理操作均有详细日志，便于跟踪和排查。

---

7. 安全机制

• 多级 SQL 风险等级（LOW/MEDIUM/HIGH/CRITICAL）

• SQL 注入与危险操作拦截

• 强制检查 WHERE 子句

• 数据库隔离安全：三级访问控制（strict/restricted/permissive）

• 跨数据库访问防护：阻止未经授权的数据库访问

• 自动隐藏敏感信息（支持自定义字段）

• 生产环境默认仅允许低风险操作

• 生产环境自动启用数据库隔离

• 多级 SQL 风险等级（LOW/MEDIUM/HIGH/CRITICAL）

• SQL 注入与危险操作拦截

• 强制检查 WHERE 子句

• 数据库隔离安全：三级访问控制（strict/restricted/permissive）

• 跨数据库访问防护：阻止未经授权的数据库访问

• 自动隐藏敏感信息（支持自定义字段）

• 生产环境默认仅允许低风险操作

• 生产环境自动启用数据库隔离

---

8. 日志与错误处理

• 日志级别可配置（LOG_LEVEL）

• 控制台与文件日志输出

• 详细记录运行状态与错误

• 完善的异常捕获与事务回滚

• 日志级别可配置（LOG_LEVEL）

• 控制台与文件日志输出

• 详细记录运行状态与错误

• 完善的异常捕获与事务回滚

---

9. 常见问题

Q：DELETE 操作未执行成功？

A：检查是否包含 WHERE 条件。没有 WHERE 条件属于高风险操作，需在 ALLOWED_RISK_LEVELS 中允许 CRITICAL。

Q：DELETE 操作为什么无法执行？ A：检查是否包含 WHERE 子句。不带 WHERE 子句的 DELETE 属于高风险操作（CRITICAL），必须在 ALLOWED_RISK_LEVELS 中允许。

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

A：设置 SENSITIVE_INFO_FIELDS，例如：SENSITIVE_INFO_FIELDS=password,token

Q：如何自定义敏感字段？ A：设置 SENSITIVE_INFO_FIELDS，例如：SENSITIVE_INFO_FIELDS=password,token

Q：如何启用数据库隔离？

A：设置 ENABLE_DATABASE_ISOLATION=true 和 DATABASE_ACCESS_LEVEL=strict，或使用 ENV_TYPE=production 自动启用。

Q：如何启用数据库隔离？ A：设置 ENABLE_DATABASE_ISOLATION=true 和 DATABASE_ACCESS_LEVEL=strict，或使用 ENV_TYPE=production 自动启用。

Q：数据库隔离后无法查询系统表？

A：strict 模式禁止访问系统表。可改用 restricted 模式，或确认是否确实需要系统表访问权限。

Q：启用数据库隔离后无法查询系统表？ A：strict 模式禁止访问系统表。可改用 restricted 模式，或确认是否确实需要系统表访问权限。

Q：limit 参数报错？

A：limit 必须为非负整数。

Q：limit 参数错误？ A：limit 必须为非负整数。

---

10. 贡献指南 / 贡献指南

欢迎通过 Issue 和 Pull Request 参与改进。 欢迎通过 Issue 和 Pull Request 贡献改进。

---

11. 许可证 / 许可证

MIT License

本软件按“原样”提供，不提供任何形式的明示或暗示保证，包括但不限于对适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论是在合同诉讼、侵权行为还是其他方面；这些责任可能产生于、源于或与本软件有关，也可能与本软件的使用或其他交易有关。 本软件按“原样”提供，不作任何形式的明示或暗示保证，包括但不限于适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论这些责任产生于合同、侵权还是其他诉因，也无论其是否因本软件产生、源于本软件、与本软件有关，或因使用本软件或进行其他与本软件有关的交易而产生。