MCP + Cherry Studio 实战：MySQL MCP 服务搭建与应用(本地部署)
一、本地部署核心优势
- 数据零泄露：数据库和 MCP 服务均运行在本地，无需暴露公网，符合企业内网安全要求；
- 无网络依赖：断网环境下仍可正常调用 MySQL MCP 服务；
- 调试更高效：本地日志实时查看，问题定位更快；
- 适配所有系统：Windows/Mac/Linux 操作步骤统一，仅路径格式略有差异。
二、本地环境前置检查
2.1 必装工具（本地已有的可跳过）
| 工具 | 检查方式 | 快速安装建议 |
|---|---|---|
| MySQL（本地） | 终端执行 mysql -u root -p 能登录 | Windows：安装 XAMPP/WAMP；Mac：brew install mysql；Linux：apt install mysql-server |
| Python 3.10+ | 终端执行 python --version | 官网下载：https://www.python.org/downloads/ |
| Cherry Studio | 能正常启动客户端 | 官网下载：https://cherry-ai.com/ |
| pip/uv | 终端执行 pip --version 或 uv --version | python -m ensurepip --upgrade（pip）；pip install uv（uv） |
2.2 本地 MySQL 基础配置（关键！）
1. 确认本地 MySQL 运行状态
- Windows：打开服务面板，确认「MySQL」服务状态为「正在运行」；
- Mac：
brew services list查看 mysql 状态，未运行则执行brew services start mysql； - Linux：
systemctl status mysql，未运行则执行systemctl start mysql。
2. 创建本地测试库/表（避免操作生产数据）
登录本地 MySQL 执行以下 SQL（密码为你的本地 MySQL root 密码）：
-- 登录本地 MySQL mysql -u root -p -- 1. 创建仅本地使用的测试库CREATEDATABASEIFNOTEXISTS local_mcp_mysql;USE local_mcp_mysql;-- 2. 创建测试表（以订单表为例，适配接口测试场景）CREATETABLEIFNOTEXISTS test_order ( order_id INTAUTO_INCREMENTPRIMARYKEY, order_no VARCHAR(32)UNIQUENOTNULL, user_id INTNOTNULL, amount DECIMAL(10,2)NOTNULL, create_time DATETIMEDEFAULTCURRENT_TIMESTAMP)ENGINE=InnoDBDEFAULTCHARSET=utf8mb4;-- 3. 插入本地测试数据INSERTINTO test_order (order_no, user_id, amount)VALUES('LOCAL_MCP_001',1001,99.90),('LOCAL_MCP_002',1002,199.90);-- 4. 授权本地账号（仅允许 127.0.0.1/localhost 访问，杜绝外部连接）GRANTALLPRIVILEGESON local_mcp_mysql.*TO'root'@'localhost' IDENTIFIED BY'你的本地MySQL密码'; FLUSH PRIVILEGES;三、本地 MySQL MCP 服务搭建（核心步骤）
3.1 本地创建 MCP 服务目录（统一路径，避免混乱）
Windows 示例（建议）：
# 打开 cmd 终端，创建目录mkdir D:\local_mcp\mysql_mcp cd D:\local_mcp\mysql_mcp Mac/Linux 示例：
mkdir -p ~/local_mcp/mysql_mcp cd ~/local_mcp/mysql_mcp 3.2 安装本地 MySQL MCP 依赖（虚拟环境隔离）
# 1. 创建本地虚拟环境（仅本地使用，避免污染全局依赖） uv venv local_mysql_env # 2. 激活虚拟环境# Windows local_mysql_env\Scripts\activate # Mac/Linuxsource local_mysql_env/bin/activate # 3. 安装本地 MySQL MCP 核心包（适配本地数据库） uv pip install mcp-mysql python-dotenv pymysql 3.3 编写本地 MySQL MCP 服务脚本（仅本地连接）
在 mysql_mcp 目录下创建 local_mysql_mcp.py（核心脚本，仅连接本地 MySQL）：
# local_mysql_mcp.pyimport os import sys from dotenv import load_dotenv from mcp_mysql import MySQLMCP import pymysql # 加载本地环境变量（仅本地读取，不对外暴露） load_dotenv()# 本地 MySQL 连接配置（固定本地地址，禁止公网访问） LOCAL_MYSQL_CONFIG ={"host": os.getenv("MYSQL_HOST","127.0.0.1"),# 强制本地地址，禁止修改为0.0.0.0"port":int(os.getenv("MYSQL_PORT",3306)),"user": os.getenv("MYSQL_USER","root"),"password": os.getenv("MYSQL_PASSWORD",""),# 本地MySQL密码"database": os.getenv("MYSQL_DB","local_mcp_mysql"),# 本地测试库"charset":"utf8mb4","connect_timeout":5,# 本地连接超时（短一点，快速失败）"local_infile":True# 启用本地文件导入（仅本地使用）}# 本地连接测试（启动前校验）deftest_local_mysql_conn():try: conn = pymysql.connect(**LOCAL_MYSQL_CONFIG) cursor = conn.cursor() cursor.execute("SELECT 1")print("[本地测试] MySQL 连接成功！") conn.close()returnTrueexcept Exception as e:print(f"[本地测试] MySQL 连接失败：{str(e)}") sys.exit(1)# 启动本地 MySQL MCP 服务（仅 STDIO 协议，适配 Cherry Studio 本地调用）defstart_local_mysql_mcp():# 先校验本地连接ifnot test_local_mysql_conn():return# 初始化本地 MCP 服务 mcp = MySQLMCP(config=LOCAL_MYSQL_CONFIG)print("[启动成功] 本地 MySQL MCP 服务已启动（仅本地访问）")# 运行 STDIO 服务（Cherry Studio 本地调用的核心协议） mcp.run_stdio()if __name__ =="__main__":# 强制限定仅本地运行，禁止远程访问if LOCAL_MYSQL_CONFIG["host"]notin["127.0.0.1","localhost"]:print("[错误] 本地 MCP 服务仅允许连接 127.0.0.1/localhost！") sys.exit(1) start_local_mysql_mcp()3.4 创建本地环境变量文件（.env）
在同目录下创建 .env 文件（填写本地 MySQL 信息，仅本地可见）：
# 本地 MySQL 配置（仅本地使用，请勿提交到任何仓库） MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_USER=root MYSQL_PASSWORD=你的本地MySQL密码 # 如：123456 或空（无密码时填""） MYSQL_DB=local_mcp_mysql 3.5 本地测试 MCP 服务启动
# 确保已激活虚拟环境，执行脚本 python local_mysql_mcp.py ✅ 成功提示：[本地测试] MySQL 连接成功！
[启动成功] 本地 MySQL MCP 服务已启动（仅本地访问）
❌ 失败排查：
- 提示密码错误：核对
.env中的MYSQL_PASSWORD； - 提示数据库不存在：重新执行 2.2 节的建库 SQL；
- 提示连接拒绝：确认本地 MySQL 服务已启动。
四、Cherry Studio 对接本地 MySQL MCP 服务
4.1 配置本地 MCP 服务（关键！）
- 启动 Cherry Studio（本地客户端），进入「设置 → MCP 服务器 → 添加 MCP 服务器」；
- 填写纯本地配置（绝对路径必须准确）：
| 配置项 | 填写值（示例） | 说明 |
|---|---|---|
| 名称 | Local-MySQL-MCP | 自定义，便于识别 |
| 类型 | STDIO | 本地调用首选协议，无需端口/网络 |
| 命令 | python D:\local_mcp\mysql_mcp\local_mysql_mcp.py | Windows 绝对路径（替换为你的实际路径） Mac/Linux： /Users/xxx/local_mcp/mysql_mcp/local_mysql_mcp.py |
| 工作目录 | D:\local_mcp\mysql_mcp | 脚本所在目录（与命令路径一致） |
| 环境变量（可选） | 无需填写 | 已通过 .env 文件配置 |
- 点击「测试连接」，提示「连接成功」后保存，并开启服务（开关变绿）。
4.2 本地调用 MySQL MCP 实战（自然语言操作）
在 Cherry Studio 对话页输入以下指令（纯本地执行，无网络依赖）：
你是本地数据库管理员，仅通过 Local-MySQL-MCP 服务操作本地数据库，步骤： 1. 查询 local_mcp_mysql 库中 test_order 表的所有数据； 2. 新增一条测试订单：order_no='LOCAL_MCP_003', user_id=1003, amount=299.90； 3. 再次查询 test_order 表，确认新增数据存在； 4. 统计 test_order 表的总订单数和总金额； 5. 输出所有操作的 SQL 语句和执行结果（仅展示，无需让我手动执行）。 ✅ 本地执行结果示例：
### 1. 查询所有订单数据 执行 SQL：SELECT * FROM test_order; 结果： +----------+-------------+---------+--------+---------------------+ | order_id | order_no | user_id | amount | create_time | +----------+-------------+---------+--------+---------------------+ | 1 | LOCAL_MCP_001 | 1001 | 99.90 | 2026-01-15 15:00:00 | | 2 | LOCAL_MCP_002 | 1002 | 199.90 | 2026-01-15 15:00:00 | +----------+-------------+---------+--------+---------------------+ ### 2. 新增测试订单 执行 SQL：INSERT INTO test_order (order_no, user_id, amount) VALUES ('LOCAL_MCP_003', 1003, 299.90); 结果：成功插入 1 条数据 ### 3. 验证新增数据 执行 SQL：SELECT * FROM test_order WHERE order_no='LOCAL_MCP_003'; 结果：存在该订单，数据正确 ### 4. 统计数据 执行 SQL：SELECT COUNT(*) AS total_count, SUM(amount) AS total_amount FROM test_order; 结果：总订单数=3，总金额=599.70 元 ### 总结：所有本地数据库操作执行成功（纯本地运行，无公网访问） 五、本地部署避坑指南（纯本地专属）
| 问题现象 | 本地专属原因 | 解决方案 |
|---|---|---|
| Cherry 提示“找不到 Python 解释器” | Windows 未配置 Python 环境变量，或虚拟环境未激活 | 1. 将 Python 安装路径（如 C:\Python310）添加到系统环境变量； 2. 命令中使用虚拟环境的 Python 绝对路径： D:\local_mcp\mysql_mcp\local_mysql_env\Scripts\python.exe |
| MCP 服务启动后立即退出 | 本地 MySQL 密码为空，但 .env 中填了空字符串 | 1. 将 .env 中 MYSQL_PASSWORD= 留空（不加引号）；2. 或给本地 MySQL 设置密码： ALTER USER 'root'@'localhost' IDENTIFIED BY '新密码'; |
| Mac/Linux 提示“Permission denied” | 脚本无执行权限 | 执行 chmod +x ~/local_mcp/mysql_mcp/local_mysql_mcp.py |
| 中文乱码（本地查询） | 本地 MySQL 字符集不是 utf8mb4 | 1. 执行 ALTER DATABASE local_mcp_mysql CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;；2. 重启本地 MySQL 服务 |
| Cherry 连接 MCP 超时（Windows） | 杀毒软件拦截了本地 STDIO 通信 | 临时关闭杀毒软件，或将 Cherry Studio 和 Python 加入白名单 |
六、本地 MCP 服务优化（便捷使用）
6.1 本地一键启动脚本（Windows 批处理）
创建 start_local_mysql_mcp.bat（双击即可启动，无需手动输命令）：
@echo off echo 激活本地虚拟环境... D:\local_mcp\mysql_mcp\local_mysql_env\Scripts\activate.bat echo 启动本地 MySQL MCP 服务... python D:\local_mcp\mysql_mcp\local_mysql_mcp.py pause 6.2 Mac/Linux 一键启动脚本
创建 start_local_mysql_mcp.sh：
#!/bin/bashecho"激活本地虚拟环境..."source ~/local_mcp/mysql_mcp/local_mysql_env/bin/activate echo"启动本地 MySQL MCP 服务..." python ~/local_mcp/mysql_mcp/local_mysql_mcp.py 授权并运行：
chmod +x start_local_mysql_mcp.sh ./start_local_mysql_mcp.sh 6.3 本地日志记录（便于调试）
修改 local_mysql_mcp.py，添加本地日志：
# 新增日志配置（仅本地保存）import logging logging.basicConfig( filename='./local_mysql_mcp.log',# 日志文件保存在本地目录 level=logging.INFO,format='%(asctime)s - %(levelname)s - %(message)s')# 在 test_local_mysql_conn 中添加日志 logging.info("本地 MySQL 连接测试开始")# 在 start_local_mysql_mcp 中添加日志 logging.info("本地 MySQL MCP 服务启动成功")七、总结（本地部署核心要点）
- 核心配置：本地 MySQL MCP 服务强制绑定
127.0.0.1，杜绝公网访问，保障数据安全； - 协议选择：优先使用 STDIO 协议，无需配置端口、防火墙，纯本地进程通信，稳定性最高；
- 依赖隔离：通过虚拟环境安装 MCP 依赖，避免与本地其他 Python 项目冲突；
- 便捷使用：一键启动脚本替代手动命令，降低本地使用成本。
