星战科技xingzhan.cloud
返回市场
mysql-mcp服务器-sse

mysql-mcp服务器-sse

作者：mangooer88 星标更新：2025-06-19
安装使用来源：spider==github.com

项目介绍

MySQL 查询服务器/MySQL 查询服务器

1. 项目简介

该项目是一个基于MCP框架的MySQL查询服务器，通过SSE协议支持实时数据库操作，并具有全面的安全性、日志记录、配置以及敏感信息保护机制。适用于开发、测试和生产环境中的安全MySQL数据访问。

该项目是一个基于MCP框架的MySQL查询服务器，通过SSE协议支持实时数据库操作。它具备全面的安全性、日志记录、配置以及敏感信息保护机制，适用于开发、测试和生产环境中的安全MySQL数据访问。

2. 主要特性/关键特性

  • 基于FastMCP框架，异步高性能
  • 支持高并发数据库连接池，参数灵活可调
  • 支持SSE实时推送
  • 丰富的MySQL元数据和结构查询API
  • 自动事务管理和回滚
  • 多级SQL风险控制和注入防护
  • 数据库隔离安全：防止跨数据库访问并支持三级访问控制
  • 敏感信息自动隐藏和定制
  • 灵活的环境变量配置
  • 完整的日志和错误处理
  • 支持Docker，快速部署
  • 基于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 并根据实际情况进行修改。 复制 .env.example 到 .env 并按需修改。

启动服务/启动服务器

python -m src.server

默认监听：http://127.0.0.1:3000/sse 默认端点：http://127.0.0.1:3000/sse

4. 目录结构/项目结构

.
├── src/
│   ├── server.py           # 主服务器入口 / 主服务器入口
│   ├── config.py           # 配置项定义 / 配置项定义
│   ├── validators.py       # 参数校验 / 参数校验
│   ├── db/
│   │   └── mysql_operations.py # 数据库操作 / 数据库操作
│   ├── security/
│   │   ├── interceptor.py      # SQL拦截 / SQL拦截
│   │   ├── query_limiter.py    # 风险控制 / 风险控制
│   │   └── sql_analyzer.py     # SQL分析 / SQL分析
│   └── tools/
│       ├── mysql_tool.py           # 基础查询 / 基础查询
│       ├── mysql_metadata_tool.py  # 元数据查询 / 元数据查询
│       ├── mysql_info_tool.py      # 信息查询 / 信息查询
│       ├── mysql_schema_tool.py    # 结构查询 / 结构查询
│       └── metadata_base_tool.py   # 工具基类 / 工具基类
├── tests/                  # 测试 / 测试
├── .env.example            # 环境变量示例 / 环境变量示例
└── requirements.txt        # 依赖 / 依赖

5. 环境变量与配置

变量名称描述默认值/默认值
HOST服务器监听地址/服务器监听地址127.0.0.1
PORT服务器监听端口/服务器监听端口3000
MYSQL_HOSTMySQL 服务器地址/MySQL 服务器主机localhost
MYSQL_PORTMySQL 服务器端口/MySQL 服务器端口3306
MYSQL_USERMySQL 用户名/MySQL 用户名root
MYSQL_PASSWORDMySQL 密码/MySQL 密码(空/空)
MYSQL_DATABASE要连接的数据库名/数据库名(空/空)
DB_TIMEOUT连接超时时间（秒）/连接超时时间（秒）5
DB_AUTH_PLUGIN认证插件类型/认证插件类型mysql_native_password
DB_POOL_ENABLED是否启用连接池/是否启用连接池（真/假）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环境类型（开发/生产）/环境类型开发
ALLOWED_RISK_LEVELS允许的风险级别（逗号分隔）/允许的风险级别LOW, MEDIUM
ALLOW_SENSITIVE_INFO允许查询敏感字段/允许敏感信息（真/假）false
SENSITIVE_INFO_FIELDS自定义敏感字段模式（逗号分隔）/自定义敏感字段(空/空)
MAX_SQL_LENGTH最大SQL语句长度/最大SQL长度5000
BLOCKED_PATTERNS被阻止的SQL模式（逗号分隔）/被阻止的SQL模式(空/空)
ENABLE_QUERY_CHECK启用查询安全检查/启用查询检查（真/假）true
ENABLE_DATABASE_ISOLATION启用数据库隔离（真/假）false
DATABASE_ACCESS_LEVEL数据库访问级别（严格/受限/许可）许可
LOG_LEVEL日志级别（调试/信息/...）/日志级别调试

注意：某些MySQL云服务需要指定DB_AUTH_PLUGIN为mysql_native_password。

MySQL 8.0 认证支持

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

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

认证插件比较

认证插件/插件安全性兼容性依赖需求/依赖
mysql_native_password中等高/高无/无
caching_sha2_password高中等加密

配置建议

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

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

数据库隔离安全

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

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

访问级别

级别允许访问适用场景/使用案例
严格仅指定数据库生产环境/生产
受限指定数据库+系统库/指定+系统数据库开发环境/开发
许可所有数据库测试环境/测试

启用数据库隔离

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

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

安全效果：

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

🔒 重要：生产环境（ENV_TYPE=production）自动启用数据库隔离，使用受限模式。

🔒 重要：生产环境（ENV_TYPE=production）自动启用数据库隔离，使用受限模式。

6. 自动化与资源管理改进

自动工具注册

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

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

  • 连接池采用事件循环隔离和自动回收机制：
    • 每个事件循环都有独立的池，支持高并发和多环境部署。
    • 定期（默认每5分钟）自动回收无效或无效的连接池，防止资源泄漏。
    • 当事件循环关闭时，自动关闭相应的连接池，确保完全释放资源。
    • 支持多数据库/多租户场景扩展。
  • 所有资源管理操作都有详细的日志记录，便于跟踪和故障排除。
  • 连接池使用事件循环隔离和自动回收：
    • 每个事件循环都有自己的池，支持高并发和多环境部署。
    • 未使用的或无效的池每5分钟（默认）自动回收，防止资源泄漏。
    • 当事件循环关闭时，其池自动关闭，确保完全释放资源。
    • 准备用于多数据库/多租户场景。
  • 所有资源管理操作都有详细的日志记录，便于跟踪和故障排除。

7. 安全机制

  • 多级SQL风险等级（低/中/高/严重）

  • SQL注入和危险操作拦截

  • WHERE子句强制检查

  • 数据库隔离安全：三级访问控制（严格/受限/许可）

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

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

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

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

  • 多级SQL风险等级（低/中/高/严重）

  • SQL注入及危险操作拦截

  • 强制WHERE子句检查

  • 数据库隔离安全：三级访问控制（严格/受限/许可）

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

  • 自动敏感信息屏蔽（自定义字段）

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

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

8. 日志和错误处理

  • 可配置的日志级别（LOG_LEVEL）

  • 控制台和文件日志输出

  • 详细的操作状态和错误记录

  • 全面的异常捕获和事务回滚

  • 可配置的日志级别（LOG_LEVEL）

  • 控制台及文件日志输出

  • 详细运行状态及错误日志

  • 强大的异常捕获及事务回滚

9. 常见问题/FAQ

Q: 删除操作没有执行成功？

A: 检查是否有WHERE条件。如果没有WHERE，被认为是高风险且需要在ALLOWED_RISK_LEVELS中允许CRITICAL。

Q: 为什么DELETE不起作用？ A: 检查WHERE子句。没有WHERE的DELETE是高风险（严重），必须在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: 严格模式禁止系统表访问，可以改为受限模式或确认是否确实需要访问系统表。

Q: 启用数据库隔离后无法查询系统表？ A: 严格模式阻止系统表访问。使用受限模式或验证是否确实需要访问系统表。

Q: limit 参数报错？

A: limit 必须是非负整数。

Q: limit 参数错误？ A: limit 必须是非负整数。

10. 贡献指南

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

11. 许可证/License

MIT 许可证

本软件“按原样”提供，不附带任何形式的明示或暗示的保证，包括但不限于适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权持有者均不对因本软件、或与本软件的使用或其他交易有关的任何索赔、损害或其他责任负责，无论是合同诉讼、侵权还是其他。 软件“按原样”提供，没有任何形式的保证，无论是明示的还是默示的，包括但不限于适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权持有者均不对因本软件或与本软件的使用或其他交易有关的任何索赔、损害或其他责任负责，无论是合同诉讼、侵权还是其他。