MySQL MCP Server

MySQL 数据库的 AI 原生交互层，基于 FastMCP 构建。运行时动态连接任意 MySQL 实例，将数据库操作沉淀为 18 个结构化工具，覆盖元数据搜索、性能分析、大表洞察、阻塞诊断、慢查询分析全场景，让 LLM 智能体像资深工程师一样自主完成复杂任务，无需人工介入。

核心特性：

• 上下文感知 — 连接即采集 17 项服务器元数据（版本、隔离级别、sql_mode、buffer_pool），为 AI 提供准确运行环境上下文，避免误判。
• 生产安全 — 只读拦截 + 查询超时 + 参数化防注入 + 误杀防护 + 结果集截断 + 请求鉴权，六层防护保障生产库即接即用
• 工具化约束 — 专用工具替代自由 SQL 执行，约束 AI 行为路径，降低误操作与注入风险
• 数据探索链 — search_schema → describe_schema → sample_data → count_estimate 递进式探索，AI 在充分理解数据结构后再生成 SQL，显著提升准确率
• 故障自处理 — active_connections → lock_waits → kill_query 闭环，AI 自主完成阻塞诊断与处理
• 并发连多库 — 通过 alias 连接池同时连接多个 MySQL 实例，一个智能体可跨实例查询与诊断

工程结构

mysql-mcp-server/
├── mysql_mcp/
│   ├── __init__.py           # 包入口
│   ├── server.py             # MCP Server 入口（FastMCP + streamable-http）
│   ├── connection_manager.py  # 连接管理器，线程安全
│   └── config_loader.py      # 配置文件加载（YAML）
├── config.example.yaml       # 配置模板
├── requirements.txt          # 依赖
├── Dockerfile                # 容器构建
├── mysql-mcp.service         # systemd 服务文件
└── README.md

快速开始

1. 安装依赖

pip install -r requirements.txt

2. 配置

cp config.example.yaml config.yaml

# config.yaml
credentials:
  user: "root"
  password: "你的密码"

auth:
  key: "your-secret-key"   # 鉴权 key，客户端请求需在 X-Auth-Key 头携带

mysql:
  query_timeout_ms: 60000  # 单条查询超时（毫秒），默认 60 秒，防止长查询拖垮数据库

3. 启动

在项目根目录执行：

python -m mysql_mcp.server

Server 监听 http://0.0.0.0:8200/mcp，transport 为 streamable-http。

4. Docker 启动

docker build -t mysql-mcp-server .
docker run -d -p 8200:8200 -v $(pwd)/config.yaml:/app/config.yaml mysql-mcp-server

对接智能体

客户端配置时需带上 X-Auth-Key 头：

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient(
    {
        "mysql": {
            "transport": "streamable-http",
            "url": "http://localhost:8200/mcp",
            "headers": {"X-Auth-Key": "your-secret-key"},
        },
    },
    tool_name_prefix=True,  # 工具名加 server 名前缀，避免多 server 重名碰撞
)
tools = await client.get_tools()

跨团队共享时，各团队只需知道 URL 和 X-Auth-Key 即可连接。

本 server 的工具用裸名注册（如 connect、kill_query），消费端开启 tool_name_prefix=True 后实际调用名为 mysql_connect、mysql_kill_query 等——由适配器统一负责命名空间。

自动加载服务器元数据

mysql_connect 连接成功后会自动采集 17 项服务器元数据，作为后续工具调用的上下文，避免 AI 盲猜版本特性：

这些信息随连接返回，AI 无需额外调用即可据此选择正确的 SQL 语法与诊断方向。

工具列表

以下工具名为开启 tool_name_prefix=True 后的实际调用名；server 端以裸名注册（如 connect、kill_query），前缀由 langchain-mcp-adapters 自动添加。

使用示例

示例 1：数据探索

用户: 我刚接手 172.10.20.11:3306，帮我摸清订单相关的表结构，写个统计昨日 GMV 的 SQL

智能体自动执行:
1. mysql_connect(host="172.10.20.11", port=3306)
   → 自动获取版本、sql_mode、隔离级别等 17 项元数据
2. mysql_search_schema(keyword="order")
   → 发现 orders、order_detail、order_refund 等相关表
3. mysql_describe_schema(table="orders")
   → 拿到 DDL：字段、类型、主键、索引、注释
4. mysql_sample_data(database="shop", table="orders", limit=5)
   → 抽样真实数据，确认字段语义与金额单位
5. 综合结构与样本 → 生成准确 SQL，无需人工纠正

示例 2：性能诊断——慢查询定位与优化

用户: 172.10.20.11:3306 最近响应变慢，帮我排查

智能体自动执行:
1. mysql_connect(host="172.10.20.11", port=3306)
2. mysql_show_statement_digest(limit=10, within_hours=6)
   → 按平均耗时降序，锁定最慢的 SQL 指纹
3. mysql_explain(query="SELECT * FROM orders WHERE ...")
   → 看执行计划，发现全表扫描、未走索引
4. 综合分析 → 给出加索引建议与优化后的 SQL

示例 3：故障自处理——锁阻塞诊断与处理

用户: 172.10.20.11:3306 上有业务反馈数据库卡住，帮我处理

智能体自动执行:
1. mysql_connect(host="172.10.20.11", port=3306)
2. mysql_show_active_connections()
   → 发现多个连接处于 Locked 状态，等待时间长
3. mysql_show_lock_waits()
   → 锁阻塞关系：连接 12345 持锁不放，阻塞了 30+ 个会话
4. mysql_list_long_running_transactions(min_duration_sec=300)
   → 确认该连接对应一个 8 分钟未提交的长事务
5. mysql_kill_query(process_id=12345)
   → 终止问题 SQL，阻塞解除
6. 回报处置结果 → 无需人工介入，全程自动完成

示例 4：大表洞察

用户: 172.10.20.11:3306 磁盘快满了，帮我找出最大的表

智能体自动执行:
1. mysql_connect(host="172.10.20.11", port=3306)
2. mysql_list_large_tables(min_size_gb=5, limit=20)
   → 返回超 5GB 的表列表，附 total 总数
3. mysql_count_estimate(database="shop", table="order_log_2024")
   → 查看最大表的行数估算与最后更新时间
4. 综合分析 → 给出归档与清理建议