MCP + Cherry Studio 实战：MySQL MCP 服务搭建与应用(本地部署)

一、本地部署核心优势

二、本地环境前置检查

2.1 必装工具（本地已有的可跳过）

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. 创建仅本地使用的测试库
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;

三、本地 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/Linux
source 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.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()

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 服务（关键！）

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 元

### 总结：所有本地数据库操作执行成功（纯本地运行，无公网访问）

五、本地部署避坑指南（纯本地专属）

六、本地 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/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

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 服务启动成功")

七、总结（本地部署核心要点）