MySQL MCP Server 从零安装到使用实战，AI 直接查询数据库

前言：最近在折腾 AI + 数据库的方案时，发现一个宝藏工具 —— MySQL MCP Server。它能让 AI 助手直接安全地操作你的 MySQL 数据库，查表、执行 SQL、分析数据，一条龙服务。

但说实话，安装过程坑不少，尤其是 Windows 环境。这篇教程把我踩过的坑全记录下来了，照着做，10 分钟搞定！

一、MySQL MCP Server 到底能干啥？（先搞懂再动手）

1.1 一句话解释

MySQL MCP Server = 给 AI 装上"数据库操作员"的技能包

以前你问 AI：“帮我查一下用户表里有多少人？” AI 回你：“抱歉，我无法访问您的数据库，建议您使用 SQL 客户端工具…”

装了 MySQL MCP Server 之后： AI 直接连上你的数据库，执行 SQL，把结果甩你脸上。

1.2 MCP 是什么鬼？

MCP = Model Context Protocol（模型上下文协议）

简单说就是：AI 和外部工具之间的"翻译官"。

没有 MCP 时，AI 只能聊天；有了 MCP，AI 能操作数据库、读写文件、调用 API… 就像给 AI 装上了"手和脚"。

┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ AI 助手 │ ──→ │ MCP Server │ ──→ │ MySQL │
│ (Claude等) │ ←── │ (翻译官) │ ←── │ 数据库 │
└─────────────┘ └──────────────┘ └─────────────┘
聊天 协议转换 数据存储

1.3 它能做什么？（具体到不能再具体）

核心能力一览

真实使用场景（这才是重点）

场景 1：数据分析神器

你：“帮我看一下 orders 表最近 7 天的订单趋势” AI：直接查询 → 返回结果 → 生成图表建议 → 完事

场景 2：SQL 写作助手

你：“我要查每个用户的最后登录时间，但不会写 SQL” AI：先看表结构 → 自动生成 SQL → 执行验证 → 返回结果

场景 3：数据库文档自动生成

你：“帮我生成一份 news_app 库的表结构文档” AI：遍历所有表 → 拿字段信息 → 输出 Markdown 文档

场景 4：快速排查问题

你：“为什么这个接口报错了？查一下日志表” AI：执行查询 → 定位异常数据 → 给出可能原因

场景 5：代码开发辅助

你：“我要写一个查询用户信息的接口，先看看 user 表结构” AI：返回字段列表 → 建议实体类结构 → 甚至帮你写 MyBatis XML

1.4 它不能做什么？（避免期望过高）

1.5 适合谁用？

1.6 和传统方式对比

一句话总结：这不是要取代你的数据库客户端，而是让你的 AI 助手从"只能聊天"变成"能干活"。

二、环境准备

2.1 系统要求

2.2 前置检查

打开终端（PowerShell/CMD），运行：

# 检查 Python 版本（必须 >= 3.11）
python –version
# 输出示例：Python 3.12.0 ✅

# 检查 pip
pip –version
# 输出示例：pip 24.3.1 from … ✅

# 检查 git
git –version
# 输出示例：git version 2.x.x ✅

⚠️ 如果 Python 版本低于 3.11，先去 python.org 升级！

别问我怎么知道的，我同事用 Python 3.9 装了一下午…

三、安装步骤（跟着做，10 分钟搞定）

📋 安装总览（先看全局）

Step 1: 环境检查 → Step 2: 克隆代码 → Step 3: 创建虚拟环境
↓
Step 4: 安装依赖 → Step 5: 配置数据库连接 → Step 6: 启动测试
↓
✅ 大功告成！AI 可以操作你的数据库了

前置条件：确保你已经有了 MySQL 数据库（本地或远程都行），并且知道：

• 数据库 IP 地址
• 端口（默认 3306）
• 用户名和密码
• 要连接的数据库名

Step 1：环境检查（这一步不能跳！）

打开 PowerShell 或 CMD，依次运行：

# ✅ 检查 Python 版本（必须 >= 3.11，这是硬性要求）
python –version
# 预期输出：Python 3.12.0 ✅
# 如果是 3.10 或更低 → 先去 python.org 升级！

# ✅ 检查 pip（Python 包管理器）
pip –version
# 预期输出：pip 24.x.x ✅

# ✅ 检查 git（用来下载代码）
git –version
# 预期输出：git version 2.x.x ✅

⚠️ 踩坑提醒：Python 版本低于 3.11 会直接报错，别浪费时间往下走。

全部通过？进入下一步。

Step 2：克隆官方代码

# 2.1 创建项目目录（路径可以自定义）
mkdir D:\\project\\McpSever\\mysql-mcp-server

# 2.2 进入目录
cd D:\\project\\McpSever\\mysql-mcp-server

# 2.3 克隆代码（最后的 . 表示克隆到当前目录，不会多套一层文件夹）
git clone https://github.com/designcomputer/mysql_mcp_server.git .

验证：目录下应该能看到这些文件：

D:\\project\\McpSever\\mysql-mcp-server\\
├── mysql_mcp_server/ # 核心代码目录
├── pyproject.toml # 项目配置文件
├── requirements.txt # 依赖列表
├── README.md # 官方说明
└── …其他文件

Step 3：创建虚拟环境（隔离依赖，避免污染系统 Python）

# 3.1 在项目目录下创建虚拟环境
python -m venv .venv

# 3.2 激活虚拟环境（根据你的终端选择）

# ===== Windows PowerShell =====
.\\venv\\Scripts\\Activate.ps1

# ===== Windows CMD =====
# .\\venv\\Scripts\\activate.bat

# ===== Linux / macOS =====
# source .venv/bin/activate

成功标志：终端前面出现 (venv) 前缀

(venv) PS D:\\project\\McpSever\\mysql-mcp-server>
^^^^
这个就是激活成功的标志

💡 为什么用虚拟环境？

避免把各种包装到系统 Python 里，导致版本冲突。 就像给每个项目一个独立的工作台，互不干扰。

Step 4：安装依赖包

# 以开发模式安装（推荐，方便后续调试和修改）
pip install -e .

安装过程会自动下载这些依赖：

等待安装完成…（第一次会比较慢，要下载一堆东西）

验证是否安装成功：

pip show mysql-mcp-server

预期输出：

Name: mysql_mcp_server
Version: 0.3.1 ← 看到这个就对了 ✅
Location: D:\\…\\mysql-mcp-server\\.venv\\Lib\\site-packages

看到 Version: 0.3.1 就说明安装成功了！🎉

Step 5：配置数据库连接（关键步骤！）

方式 A：环境变量文件（推荐新手使用）

在项目根目录创建 .env 文件：

# MySQL 连接配置（改成你自己的信息）
MYSQL_HOST=192.168.191.128 # ← 你的数据库 IP
MYSQL_PORT=3306 # ← 端口（默认 3306）
MYSQL_USER=root # ← 用户名
MYSQL_PASSWORD=123456 # ← 密码
MYSQL_DATABASE=news_app # ← 数据库名（不填则支持多库切换）

# ⚠️ Windows 用户必看！下面这行必须加！
MYSQL_USE_PURE=true # ← 使用纯 Python 模式（重要！）

💡 为什么需要 MYSQL_USE_PURE=true？

这是本文第一个重点踩坑点！MySQL Connector 默认尝试用 C 扩展加速，但 Windows 下经常编译失败或缺失。

设置为 true 后改用纯 Python 实现，虽然性能略低，但稳定可靠，开发环境完全够用。

不加这行的话，报错长这样：

ImportError: MySQL Connector/Python C Extension not available

方式 B：Claude Desktop 配置文件（推荐正式使用）

如果你要用 Claude Desktop，找到配置文件：

复制以下内容进去（记得改连接信息）：

{
"mcpServers": {
"mysql": {
"command": "D:\\\\project\\\\McpSever\\\\mysql-mcp-server\\\\.venv\\\\Scripts\\\\python.exe",
"args": ["-m", "mysql_mcp_server"],
"env": {
"MYSQL_HOST": "192.168.191.128",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASSWORD": "123456",
"MYSQL_DATABASE": "news_app",
"MYSQL_USE_PURE": "true"
}
}
}
}

参数对照表：

Step 6：启动并测试（见证奇迹的时刻）

6.1 命令行启动（先测试能不能跑通）

# 确保还在项目目录下
cd D:\\project\\McpSever\\mysql-mcp-server

# 确保 (venv) 还在（如果掉了就重新激活）

# 设置环境变量（PowerShell 写法）
$env:MYSQL_HOST="192.168.191.128"
$env:MYSQL_PORT="3306"
$env:MYSQL_USER="root"
$env:MYSQL_PASSWORD="123456"
$env:MYSQL_DATABASE="news_app"
$env:MYSQL_USE_PURE="true"

# 启动服务
.\\.venv\\Scripts\\python.exe -m mysql_mcp_server

✅ 成功标志（看到这就说明连上了）：

2026-06-03 17:24:46,753 – mysql_mcp_server – INFO – Starting MySQL MCP server (STDIO)…

❌ 如果报错：别慌，翻到文章最后的 第七章：常见问题排查，99% 的坑我都踩过了。

6.2 用 MCP Inspector 测试（可视化测试工具）

想看看具体有哪些功能？用这个：

# 安装测试工具
pip install mcp-inspector

# 启动可视化测试界面
mcp-inspector python -m mysql_mcp_server

然后浏览器会自动打开，你能看到所有可用的工具，还能直接点击测试！

✅ 安装完成清单

做完上面 6 步后，对一下这个清单：

• Step 1: Python >= 3.11 ✅
• Step 2: 代码已克隆，目录结构正确 ✅
• Step 3: 虚拟环境已创建并激活（有 (venv) 前缀）✅
• Step 4: pip show mysql-mcp-server 能看到版本号 ✅
• Step 5: .env 或配置文件已填写连接信息 ✅
• Step 6: 启动后看到 Starting MySQL MCP server 日志 ✅

全打勾了？恭喜你，MySQL MCP Server 已经跑起来了！ 🎉🎉🎉

现在你可以去 Claude Desktop 或者其他支持 MCP 的 AI 助手里，直接跟它说：“帮我查一下数据库里有多少用户”，它会自己帮你执行 SQL 并返回结果。

六、高级配置（按需选择）

6.1 SSL/TLS 加密连接

如果你的 MySQL 开启了 SSL：

MYSQL_SSL_MODE=REQUIRED # DISABLED / REQUIRED / VERIFY_CA / VERIFY_IDENTITY
MYSQL_CONNECT_TIMEOUT=10 # 连接超时时间（秒）

6.2 SSH 隧道连接（远程数据库神器）

当数据库在内网或需要跳板机时：

# 启用 SSH 隧道
MYSQL_SSH_ENABLE=true
MYSQL_SSH_HOST=jump.example.com # 跳板机地址
MYSQL_SSH_PORT=22 # SSH 端口
MYSQL_SSH_USER=ssh_user # SSH 用户名
MYSQL_SSH_KEY_PATH=C:\\Users\\you\\.ssh\\id_rsa # SSH 私钥路径
MYSQL_SSH_REMOTE_HOST=localhost # 从跳板机看的目标主机
MYSQL_SSH_REMOTE_PORT=3306 # 目标端口
MYSQL_LOCAL_PORT=3330 # 本地映射端口

💡 这个功能太香了！以前用 Navicat 手动建隧道，现在一行配置搞定。

6.3 SSE/HTTP 模式（适合远程部署）

默认使用 STDIO（标准输入输出）模式，适合本地开发。如果要部署到服务器供多人使用：

MCP_TRANSPORT=sse # 切换到 HTTP 模式
MCP_SSE_HOST=0.0.0.0 # 监听所有网卡
PORT=8000 # HTTP 端口

然后通过 http://your-server:8000/sse 访问。

6.4 兼容性配置（老版本 MySQL）

MYSQL_CHARSET=utf8mb4 # 字符集
MYSQL_COLLATION=utf8mb4_unicode_ci # 排序规则
MYSQL_AUTH_PLUGIN=mysql_native_password # 认证插件（MySQL 5.x 可能需要）

七、常见问题排查（避坑指南）

问题 1：ImportError: MySQL Connector/Python C Extension not available

现象：

File "pooling.py", line 319, in connect
raise ImportError(ERROR_NO_CEXT)
ImportError: MySQL Connector/Python C Extension not available

原因：Windows 下 C 扩展未编译或缺失。

解决方案：

// 在 env 中添加：
"MYSQL_USE_PURE": "true"

原理：强制使用纯 Python 实现，绕过 C 扩展依赖。

问题 2：Authentication plugin ‘caching_sha2_password’ cannot be loaded

现象：

Authentication plugin 'caching_sha2_password' cannot be loaded

原因：MySQL 8.0 默认使用 caching_sha2_password 认证，旧版 Connector 不支持。

解决方案：

# 方案 A：升级 mysql-connector-python 到 >= 8.0
pip install –upgrade mysql-connector-python

# 方案 B：修改 MySQL 用户认证方式（在 MySQL 中执行）
ALTER USER 'root'@'%' IDENTIFIED WITH mysql_native_password BY '123456';
FLUSH PRIVILEGES;

问题 3：连接超时 Connection timed out

现象：

mysql.connector.errors.InterfaceError: 2003: Can't connect to MySQL server

排查清单：

• MySQL 服务是否启动？systemctl status mysql 或服务管理器查看
• 防火墙是否放行 3306 端口？
• IP 地址是否正确？（局域网用内网 IP，不要用 localhost 连远程）
• MySQL 是否允许远程连接？检查 bind-address 配置
• 云服务器是否开放安全组？

快速测试连通性：

# 测试端口是否可达
telnet 192.168.191.128 3306

# 或者用 PowerShell
Test-NetConnection -ComputerName 192.168.191.128 -Port 3306

问题 4：ModuleNotFoundError: No module named ‘mcp’

现象：提示找不到 mcp 模块。

原因：没有使用虚拟环境，或者 pip 安装到了其他 Python。

解决方案：

# 确保在虚拟环境中安装
cd D:\\project\\McpSever\\mysql-mcp-server
.\\venv\\Scripts\\Activate.ps1
pip install -e .

# 验证
which python # 应该指向 .venv 目录
pip show mcp # 应该能看到版本号

问题 5：权限不足 Access denied for user

现象：

Access denied for user 'root'@'192.168.%' (using password: YES)

解决方案：

⚠️ 生产环境严禁使用 root 账户！创建专用用户并限制权限。

八、生产环境安全建议

安全是底线，不是可选项。 数据库被删了可以恢复，但客户信任丢了就真没了。

8.1 最小权限原则（核心！）

✅ 推荐配置：只读用户（详见 第四章五节）

— 创建专用 MCP 只读用户
CREATE USER 'mcp_readonly'@'%' IDENTIFIED BY '强密码';
GRANT SELECT ON your_db.* TO 'mcp_readonly'@'%';
GRANT SHOW DATABASES ON *.* TO 'mcp_readonly'@'%';
GRANT PROCESS ON *.* TO 'mcp_readonly'@'%';
FLUSH PRIVILEGES;

权限分级参考：

8.2 敏感信息保护

❌ 错误做法：把密码写在代码里或提交到 Git。

✅ 正确做法：

8.3 网络隔离

• 不要将 MCP Server 暴露到公网
• 使用 VPN 或 SSH 隧道访问
• 配置防火墙白名单

九、总结与对比

9.1 安装方式对比

9.2 核心要点速查

✅ Python >= 3.11
✅ 使用虚拟环境（.venv）
✅ Windows 必须设置 MYSQL_USE_PURE=true
✅ 配置文件用绝对路径
✅ ✅ ✅ 必须使用只读用户（mcp_readonly）！
✅ 生产环境用专用账户
❌ 不要用 root 连接生产库
❌ 不要把密码提交到 Git
❌ 不要给 AI 写权限（除非你很清楚在干嘛）

十、延伸阅读

• 官方文档: https://github.com/designcomputer/mysql_mcp_server
• MCP 协议规范: https://modelcontextprotocol.io
• 使用案例: 项目中的 MCP_USECASES.md 文件
• 安全指南: 项目中的 SECURITY.md 文件

折腾了大半天，终于把这个 MySQL MCP Server 跑通了。说实话，文档写得不算详细，Windows 的坑也没提，所以才有了这篇文章。

现在我的 AI 助手可以直接：

• 📊 查看 news_app 库有哪些表
• 🔍 分析表结构和数据分布
• ✏️ 执行 SQL 查询并返回结果
• 📝 生成数据报告

效率提升不是一点半点，尤其是做数据分析的时候，不用来回切数据库客户端和 ChatGPT 了。

技术不难，难的是没人告诉你坑在哪。

如果这篇帮到你，点个赞，顺便帮我抢救一下发际线 😄

claude_desktop_config.json（推荐：只读用户）

{
"mcpServers": {
"mysql": {
"command": "D:\\\\project\\\\McpSever\\\\mysql-mcp-server\\\\.venv\\\\Scripts\\\\python.exe",
"args": ["-m", "mysql_mcp_server"],
"env": {
"MYSQL_HOST": "你的数据库IP",
"MYSQL_PORT": "3306",
"MYSQL_USER": "mcp_readonly",
"MYSQL_PASSWORD": "你的强密码",
"MYSQL_DATABASE": "数据库名",
"MYSQL_USE_PURE": "true"
}
}
}
}

⚠️ 安全提醒：

• MYSQL_USER 使用专用的只读账户（如 mcp_readonly）
• MYSQL_PASSWORD 使用强密码（大小写+数字+特殊字符，12位以上）
• 不要使用 root 或其他管理员账户

VS Code mcp.json

{
"mcpServers": {
"mysql": {
"type": "stdio",
"command": "uvx",
"args": [
"–from",
"mysql-mcp-server",
"mysql_mcp_server"
],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_PORT": "3306",
"MYSQL_USER": "mcp_readonly",
"MYSQL_PASSWORD": "your_strong_password",
"MYSQL_DATABASE": "your_database"
}
}
}
}

注：VS Code 方案需要安装 uv 工具。

MySQL 只读用户创建脚本（首次配置必执行）

— =============================================
— MySQL MCP Server 只读用户创建脚本
— 在 MySQL 命令行或 Navicat/DBeaver 中执行
— 需要管理员权限（root）
— =============================================

— 1. 创建用户（如果不存在）
CREATE USER IF NOT EXISTS 'mcp_readonly'@'%'
IDENTIFIED BY '请修改为强密码';

— 2. 授予只读权限（根据实际情况修改数据库名）
GRANT SELECT ON your_database.* TO 'mcp_readonly'@'%';
GRANT SHOW DATABASES ON *.* TO 'mcp_readonly'@'%';
GRANT PROCESS ON *.* TO 'mcp_readonly'@'%';

— 3. 生效
FLUSH PRIVILEGES;

— 4. 验证创建成功
SELECT user, host FROM mysql.user WHERE user = 'mcp_readonly';
SHOW GRANTS FOR 'mcp_readonly'@'%';

🎉 祝你安装顺利，一次成功！有问题欢迎评论区交流~

🙏 作者介绍

📌 写文不易，Bug 更不易。

如果这篇文章对你有帮助，可以搜一搜：空门技术栈

这里分享：

• ✅ Java / Spring AI / 企业级项目实战
• ✅ Docker / RAG知识库 / 微服务踩坑
• ✅ Python、前端、AI应用落地
• ✅ 偶尔分享一些「头发保卫战」经验 😆

一个热爱技术、持续填坑的开发者， 陪你一起少踩坑，少加班，多写优雅代码。

📖 推荐阅读

• 看了 3 天官方文档后，我决定自己写一篇 LangChain 人话教程
• GPT-5.5 变强、Spring AI 更新、Ollama 爆漏洞｜今天值得看的技术热点
• 还在复制粘贴 if-else？模板方法模式，专治重复代码！
• CSDN：LangChain 入门实战指南
• AI 为什么总"失忆"？LangChain Memory 完全指南：从 InMemory 到 Redis 实战避坑
• Java 单例模式详解：7 种实现方式 + volatile 原理 + 反射与序列化问题
• 告别手动复制接口文档！Apifox MCP + AI 自动测试让开发效率起飞

🤝 技术交流 / 项目合作

平时也会做一些技术项目与咨询，包括：

• Java / Spring Boot 企业级项目开发
• AI 应用开发（LangChain、RAG、Agent、知识库）
• Docker / Linux / 私有化部署
• 系统功能开发、接口对接、性能优化
• 疑难问题排查与技术咨询

如果你：

• 想做 AI 项目，但不确定技术方案
• 项目卡在某个 Bug 很久
• 想把 AI 接入现有系统
• 需要企业级开发支持

欢迎交流。

📮 联系方式：

• Email：2929119150@qq.com
• 也可以私信我
• 技术交流可通过个人主页联系

有些坑，一个人踩是事故；一起踩，就是经验 😎