本文介绍在本地环境部署 MySQL MCP 服务并对接 Cherry Studio 的方法。重点在于数据安全（零泄露、断网可用）与调试效率。流程包括安装 MySQL 与 Python 工具、创建测试库表、编写 MCP 服务脚本、配置环境变量及在 Cherry Studio 中通过 STDIO 协议连接。支持自然语言操作本地数据库，提供避坑指南与一键启动脚本，实现纯本地化安全调用。
| 工具 | 检查方式 | 快速安装建议 |
|---|---|---|
| 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） |
brew services list 查看 mysql 状态，未运行则执行 brew services start mysql；systemctl status mysql，未运行则执行 systemctl start mysql。登录本地 MySQL 执行以下 SQL（密码为你的本地 MySQL root 密码）：
-- 登录本地 MySQL
mysql -u root -p
-- 1. 创建仅本地使用的测试库
CREATE DATABASE IF NOT EXISTS local_mcp_mysql;
USE local_mcp_mysql;
-- 2. 创建测试表（以订单表为例，适配接口测试场景）
CREATE TABLE IF NOT EXISTS test_order (
order_id INT AUTO_INCREMENT PRIMARY KEY,
order_no VARCHAR(32) UNIQUE NOT NULL,
user_id INT NOT NULL,
amount DECIMAL(10,2) NOT NULL,
create_time DATETIME DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
-- 3. 插入本地测试数据
INSERT INTO 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 访问，杜绝外部连接）
GRANT ALL PRIVILEGES ON local_mcp_mysql.* TO 'root'@'localhost' IDENTIFIED BY '你的本地 MySQL 密码';
FLUSH PRIVILEGES;
# 打开 cmd 终端，创建目录
mkdir D:\local_mcp\mysql_mcp
cd D:\local_mcp\mysql_mcp
mkdir -p ~/local_mcp/mysql_mcp
cd ~/local_mcp/mysql_mcp
# 1. 创建本地虚拟环境（仅本地使用，避免污染全局依赖）
uv venv local_mysql_env
# 2. 激活虚拟环境
# Windows
local_mysql_env\Scripts\activate
# Mac/Linux
source local_mysql_env/bin/activate
# 3. 安装本地 MySQL MCP 核心包（适配本地数据库）
uv pip install mcp-mysql python-dotenv pymysql
在 mysql_mcp 目录下创建 local_mysql_mcp.py（核心脚本，仅连接本地 MySQL）：
# local_mysql_mcp.py
import 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 # 启用本地文件导入（仅本地使用）
}
# 本地连接测试（启动前校验）
def test_local_mysql_conn():
try:
conn = pymysql.connect(**LOCAL_MYSQL_CONFIG)
cursor = conn.cursor()
cursor.execute("SELECT 1")
print("[本地测试] MySQL 连接成功！")
conn.close()
return True
except Exception as e:
print(f"[本地测试] MySQL 连接失败：{str(e)}")
sys.exit(1)
# 启动本地 MySQL MCP 服务（仅 STDIO 协议，适配 Cherry Studio 本地调用）
def start_local_mysql_mcp():
# 先校验本地连接
if not 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"] not in ["127.0.0.1", "localhost"]:
print("[错误] 本地 MCP 服务仅允许连接 127.0.0.1/localhost！")
sys.exit(1)
start_local_mysql_mcp()
在同目录下创建 .env 文件（填写本地 MySQL 信息，仅本地可见）：
# 本地 MySQL 配置（仅本地使用，请勿提交到任何仓库）
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=你的本地 MySQL 密码 # 如：123456 或空（无密码时填""）
MYSQL_DB=local_mcp_mysql
# 确保已激活虚拟环境，执行脚本
python local_mysql_mcp.py
✅ 成功提示：
[本地测试] MySQL 连接成功！ [启动成功] 本地 MySQL MCP 服务已启动（仅本地访问）
❌ 失败排查：
.env 中的 MYSQL_PASSWORD；| 配置项 | 填写值（示例） | 说明 |
|---|---|---|
| 名称 | 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 文件配置 |
在 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）添加到系统环境变量； |
D:\local_mcp\mysql_mcp\local_mysql_env\Scripts\python.exe |
| MCP 服务启动后立即退出 | 本地 MySQL 密码为空，但 .env 中填了空字符串 | 1. 将 .env 中 MYSQL_PASSWORD= 留空（不加引号）；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;；创建 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
创建 start_local_mysql_mcp.sh：
#!/bin/bash
echo "激活本地虚拟环境..."
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
修改 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 服务启动成功")
127.0.0.1，杜绝公网访问，保障数据安全；
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online