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

一、本地部署核心优势数据零泄露数据库和 MCP 服务均运行在本地无需暴露公网符合企业内网安全要求无网络依赖断网环境下仍可正常调用 MySQL MCP 服务调试更高效本地日志实时查看问题定位更快适配所有系统Windows/Mac/Linux 操作步骤统一仅路径格式略有差异。二、本地环境前置检查2.1 必装工具本地已有的可跳过工具检查方式快速安装建议MySQL本地终端执行mysql -u root -p能登录Windows安装 XAMPP/WAMPMacbrew install mysqlLinuxapt install mysql-serverPython 3.10终端执行python --version官网下载https://www.python.org/downloads/Cherry Studio能正常启动客户端官网下载https://cherry-ai.com/pip/uv终端执行pip --version或uv --versionpython -m ensurepip --upgradepippip install uvuv2.2 本地 MySQL 基础配置关键1. 确认本地 MySQL 运行状态Windows打开服务面板确认「MySQL」服务状态为「正在运行」Macbrew services list查看 mysql 状态未运行则执行brew services start mysqlLinuxsystemctl status mysql未运行则执行systemctl start mysql。2. 创建本地测试库/表避免操作生产数据登录本地 MySQL 执行以下 SQL密码为你的本地 MySQL root 密码-- 登录本地 MySQLmysql-u root-p-- 1. 创建仅本地使用的测试库CREATEDATABASEIFNOTEXISTSlocal_mcp_mysql;USElocal_mcp_mysql;-- 2. 创建测试表以订单表为例适配接口测试场景CREATETABLEIFNOTEXISTStest_order(order_idINTAUTO_INCREMENTPRIMARYKEY,order_noVARCHAR(32)UNIQUENOTNULL,user_idINTNOTNULL,amountDECIMAL(10,2)NOTNULL,create_timeDATETIMEDEFAULTCURRENT_TIMESTAMP)ENGINEInnoDBDEFAULTCHARSETutf8mb4;-- 3. 插入本地测试数据INSERTINTOtest_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 访问杜绝外部连接GRANTALLPRIVILEGESONlocal_mcp_mysql.*TOrootlocalhostIDENTIFIEDBY你的本地MySQL密码;FLUSHPRIVILEGES;三、本地 MySQL MCP 服务搭建核心步骤3.1 本地创建 MCP 服务目录统一路径避免混乱Windows 示例建议# 打开 cmd 终端创建目录mkdirD:\local_mcp\mysql_mcpcdD:\local_mcp\mysql_mcpMac/Linux 示例mkdir-p~/local_mcp/mysql_mcpcd~/local_mcp/mysql_mcp3.2 安装本地 MySQL MCP 依赖虚拟环境隔离# 1. 创建本地虚拟环境仅本地使用避免污染全局依赖uv venv local_mysql_env# 2. 激活虚拟环境# Windowslocal_mysql_env\Scripts\activate# Mac/Linuxsourcelocal_mysql_env/bin/activate# 3. 安装本地 MySQL MCP 核心包适配本地数据库uv pipinstallmcp-mysql python-dotenv pymysql3.3 编写本地 MySQL MCP 服务脚本仅本地连接在mysql_mcp目录下创建local_mysql_mcp.py核心脚本仅连接本地 MySQL# local_mysql_mcp.pyimportosimportsysfromdotenvimportload_dotenvfrommcp_mysqlimportMySQLMCPimportpymysql# 加载本地环境变量仅本地读取不对外暴露load_dotenv()# 本地 MySQL 连接配置固定本地地址禁止公网访问LOCAL_MYSQL_CONFIG{host:os.getenv(MYSQL_HOST,127.0.0.1),# 强制本地地址禁止修改为0.0.0.0port: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:connpymysql.connect(**LOCAL_MYSQL_CONFIG)cursorconn.cursor()cursor.execute(SELECT 1)print([本地测试] MySQL 连接成功)conn.close()returnTrueexceptExceptionase:print(f[本地测试] MySQL 连接失败{str(e)})sys.exit(1)# 启动本地 MySQL MCP 服务仅 STDIO 协议适配 Cherry Studio 本地调用defstart_local_mysql_mcp():# 先校验本地连接ifnottest_local_mysql_conn():return# 初始化本地 MCP 服务mcpMySQLMCP(configLOCAL_MYSQL_CONFIG)print([启动成功] 本地 MySQL MCP 服务已启动仅本地访问)# 运行 STDIO 服务Cherry Studio 本地调用的核心协议mcp.run_stdio()if__name____main__:# 强制限定仅本地运行禁止远程访问ifLOCAL_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_HOST127.0.0.1 MYSQL_PORT3306 MYSQL_USERroot MYSQL_PASSWORD你的本地MySQL密码 # 如123456 或空无密码时填 MYSQL_DBlocal_mcp_mysql3.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.pyWindows 绝对路径替换为你的实际路径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_noLOCAL_MCP_003, user_id1003, amount299.90 3. 再次查询 test_order 表确认新增数据存在 4. 统计 test_order 表的总订单数和总金额 5. 输出所有操作的 SQL 语句和执行结果仅展示无需让我手动执行。✅ 本地执行结果示例### 1. 查询所有订单数据 执行 SQLSELECT * 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. 新增测试订单 执行 SQLINSERT INTO test_order (order_no, user_id, amount) VALUES (LOCAL_MCP_003, 1003, 299.90); 结果成功插入 1 条数据 ### 3. 验证新增数据 执行 SQLSELECT * FROM test_order WHERE order_noLOCAL_MCP_003; 结果存在该订单数据正确 ### 4. 统计数据 执行 SQLSELECT 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.exeMCP 服务启动后立即退出本地 MySQL 密码为空但 .env 中填了空字符串1. 将.env中MYSQL_PASSWORD留空不加引号2. 或给本地 MySQL 设置密码ALTER USER rootlocalhost IDENTIFIED BY 新密码;Mac/Linux 提示“Permission denied”脚本无执行权限执行chmod x ~/local_mcp/mysql_mcp/local_mysql_mcp.py中文乱码本地查询本地 MySQL 字符集不是 utf8mb41. 执行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 pause6.2 Mac/Linux 一键启动脚本创建start_local_mysql_mcp.sh#!/bin/bashecho激活本地虚拟环境...source~/local_mcp/mysql_mcp/local_mysql_env/bin/activateecho启动本地 MySQL MCP 服务...python ~/local_mcp/mysql_mcp/local_mysql_mcp.py授权并运行chmodx start_local_mysql_mcp.sh ./start_local_mysql_mcp.sh6.3 本地日志记录便于调试修改local_mysql_mcp.py添加本地日志# 新增日志配置仅本地保存importlogging logging.basicConfig(filename./local_mysql_mcp.log,# 日志文件保存在本地目录levellogging.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 项目冲突便捷使用一键启动脚本替代手动命令降低本地使用成本。