MySQL MCP 服务本地部署与 Cherry Studio 应用实践

三、本地 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 服务（关键！）

1. 启动 Cherry Studio（本地客户端），进入「设置 → MCP 服务器 → 添加 MCP 服务器」；
2. 填写纯本地配置（绝对路径必须准确）：

3. 点击「测试连接」，提示「连接成功」后保存，并开启服务（开关变绿）。

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 元

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

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

2. 命令中使用虚拟环境的 Python 绝对路径：D:\local_mcp\mysql_mcp\local_mysql_env\Scripts\python.exe | | MCP 服务启动后立即退出 | 本地 MySQL 密码为空，但 .env 中填了空字符串 | 1. 将 .env 中 MYSQL_PASSWORD= 留空（不加引号）；
3. 或给本地 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;；
4. 重启本地 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/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 服务启动成功")

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

1. 核心配置：本地 MySQL MCP 服务强制绑定 127.0.0.1，杜绝公网访问，保障数据安全；
2. 协议选择：优先使用 STDIO 协议，无需配置端口、防火墙，纯本地进程通信，稳定性最高；
3. 依赖隔离：通过虚拟环境安装 MCP 依赖，避免与本地其他 Python 项目冲突；
4. 便捷使用：一键启动脚本替代手动命令，降低本地使用成本。