1. 本地 MySQL 到 Agent 的链路为什么总在 MCP 这步卡住Fastmcp 是一个用 Python 写 MCP Server 的轻量框架它能让你把本地 MySQL 的查询能力包装成 Agent 可调用的工具。适合谁适合手头有本地数据库、想让 Cursor 或 Claude Desktop 这类客户端直接查数据的开发者。我这次的目标很明确用 conda 建环境写一个 Fastmcp 服务连上本地 MySQL最后在 agent-cursor 里配好 MCP让 Agent 能回答“年龄大于 28 的用户有几个”这种问题。为什么不用 uv我试过uv 装包确实快但它替代的是 pip不是 conda。conda 管的是 Python 版本和系统级依赖uv 管的是包安装。两者可以配合但如果你机器上已经有 conda 环境直接用 conda 更省心不用再折腾 uv 的虚拟环境路径。所以这篇全程用 conda。整条链路分四段MySQL 建库建表、conda 环境装 Fastmcp 和 pymysql、写 MCP 工具函数、在 Cursor 里配 MCP Server。每一段都有坑尤其是 Cursor 的 MCP 配置格式和 Fastmcp 的启动方式配错了就是local proxy failed或者reading choices报错。下面按顺序走每步都给可复制的命令和配置。先确认你本地有 MySQL。没有的话去官网下 MySQL 9.x 的 Windows 安装包装完把bin目录加到系统环境变量。验证方式打开 PowerShell输入mysql --version能打印版本号就说明环境变量配好了。这一步不做后面mysql -u root -p会提示命令找不到。数据库建好后创建一个测试库和一张 user 表。我用的库名是mcp表名user字段就 id、name、age 三个。数据插 10 条年龄从 22 到 35 不等方便后面验证“大于某年龄的个数”这个查询逻辑。SQL 文件放在E:\mysql-9.3.0-winx64\mcp.sql你可以放任意路径执行时换成自己的。CREATE DATABASE mcp; USE mcp; CREATE TABLE user ( id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(50) NOT NULL, age INT NOT NULL ); INSERT INTO user (name, age) VALUES (Alice, 23), (Bob, 30), (Charlie, 27), (David, 35), (Eve, 22), (Frank, 28), (Grace, 31), (Heidi, 26), (Ivan, 29), (Judy, 24);执行导入用重定向命令注意 PowerShell 里不是原生支持得用cmd /c或者直接在 cmd 里跑。我实测 PowerShell 下这样写会报“不支持重定向”换成下面这条cmd /c mysql -u root -p mcp E:\mysql-9.3.0-winx64\mcp.sql输入密码后没报错就说明导入成功。验证一下mysql -u root -p登录然后USE mcp;、SHOW TABLES;、SELECT * FROM user;能看到 10 行数据就对了。这一步是整个链路的数据基础数据没进去后面 MCP 查出来永远是 0。2. conda 环境与 Fastmcp 依赖安装的完整命令conda 建环境这步很多人图省事直接用 base但 base 里包太杂后面装mcp[cli]和fastmcp容易版本冲突。我建议单独建一个名字叫mysqlmcpPython 版本用 3.11兼容性最好。conda create -n mysqlmcp python3.11 -y conda activate mysqlmcp激活后命令行前面会显示(mysqlmcp)。接下来装三个包mcp[cli]是 MCP 协议的核心库fastmcp是 Fastmcp 框架本身pymysql是 MySQL 的 Python 驱动。注意mcp[cli]带方括号PowerShell 里方括号可能被解析成通配符所以要用引号包起来。python -m pip install mcp[cli] pip install fastmcp pip install pymysql装完验证一下pip show fastmcp和pip show pymysql能打印版本和路径就说明装好了。如果pip show mcp报找不到说明mcp[cli]没装成功重跑第一条命令注意引号别丢。这里有个细节Fastmcp 的导入方式有两种旧版是from mcp.server.fastmcp import FastMCP新版是from fastmcp import FastMCP。我用的新版导入路径短而且mcp.tool()装饰器的行为更稳定。如果你装完发现from fastmcp import FastMCP报ModuleNotFoundError检查一下是不是装到了 base 环境而不是mysqlmcp环境。conda list里能看到当前环境装了哪些包。环境建好后在 Cursor 里新建一个空文件mysql.py位置随意我放在项目根目录。这个文件就是 MCP Server 的入口。写之前先确认 conda 环境的 Python 路径后面 Cursor 配置里要用绝对路径不能用python这种相对命令否则 Cursor 启动 MCP 时找不到解释器。conda activate mysqlmcp where python输出类似C:\Users\你的用户名\miniconda3\envs\mysqlmcp\python.exe把这个路径记下来第 4 节配置 Cursor 时直接填进去。3. 可复制的 Fastmcp 服务脚本与 MySQL 连接参数MCP Server 的核心是一个工具函数输入年龄返回 user 表里年龄大于该值的记录数。用mcp.tool()装饰器注册Fastmcp 会自动把它暴露成 Agent 可调用的工具。连接参数里 host 用localhostport 默认3306user 是rootpassword 填你自己的database 填mcp。from fastmcp import FastMCP import pymysql mcp FastMCP(MySQLMCP) mcp.tool() def analysis_data(age: int) - int: try: conn pymysql.connect( hostlocalhost, port3306, userroot, password你的密码, databasemcp ) cursor conn.cursor() cursor.execute(SELECT COUNT(*) FROM user WHERE age %s, (age,)) result cursor.fetchone()[0] cursor.close() conn.close() return result except Exception as e: print(数据库操作出错, e) raise if __name__ __main__: mcp.run()注意 SQL 里我用的是%s占位符加参数元组不是 f-string 拼接。f-string 拼接在参数是数字时没问题但如果是字符串会有 SQL 注入风险养成参数化查询的习惯。cursor.fetchone()[0]取的是 COUNT 的结果返回 int。mcp.run()默认用 stdio 传输这是 MCP 客户端最常用的方式。Cursor 启动这个脚本后通过标准输入输出和它通信。所以脚本里不要加print调试信息会污染 stdio 通道导致 Cursor 解析失败。要调试就用日志文件或者sys.stderr。保存文件后先在终端里手动跑一下确认脚本本身没语法错误conda activate mysqlmcp python mysql.py如果卡住不动说明服务正常启动了在等 stdio 输入。按CtrlC退出。如果报pymysql.err.OperationalError检查 MySQL 服务是否启动、密码是否正确、端口是否被占用。接下来配置 Cursor 的 MCP。Cursor 的 MCP 配置文件在%USERPROFILE%\.cursor\mcp.jsonWindows 下就是C:\Users\你的用户名\.cursor\mcp.json。如果文件不存在就新建。配置格式是 JSONmcpServers下面每个 key 是一个服务名command填 conda 环境的 python 绝对路径args填脚本的绝对路径。{ mcpServers: { mysqlmcp: { command: C:\\Users\\你的用户名\\miniconda3\\envs\\mysqlmcp\\python.exe, args: [ E:\\projects\\mysql.py ] } } }路径里的反斜杠要双写JSON 里\是转义字符。command和args都必须是绝对路径相对路径 Cursor 解析不了。保存后重启 Cursor在设置里找到 MCP 面板应该能看到mysqlmcp显示为绿色或 connected 状态。如果你用的是 Claude Desktop配置文件在%APPDATA%\Claude\claude_desktop_config.json格式一样把mcpServers那段粘进去就行。Codex 的话配置在auth.json同级的config.toml里用 TOML 格式写[mcp_servers.mysqlmcp]command 和 args 同上。三件套就是 Base URL、Key、Model IDMCP 配置里不需要 Base URL 和 Key那是模型调用才要的MCP 只关心 command 和 args。4. 验证请求与成功结果从 Inspector 到 Cursor Agent配好之后别急着在 Cursor 里问先用 MCP Inspector 单独验证服务能不能正常响应。Inspector 是 Node.js 自带的调试工具不需要额外安装只要你有 Node.js。检查一下node --version能打印版本就行。没有的话去 Node.js 官网下 LTS 版本装上。启动 Inspector 的命令是npx modelcontextprotocol/inspector后面跟启动 MCP Server 的命令。注意一定要先激活 conda 环境否则 Inspector 用的 Python 不是mysqlmcp环境里的会报ModuleNotFoundError。conda activate mysqlmcp npx modelcontextprotocol/inspector python E:\projects\mysql.py跑起来后终端会打印一个http://localhost:5173之类的地址浏览器打开。界面左侧点Connect然后点Tools标签再点List Tools。如果配置正确能看到analysis_data这个工具参数是age类型integer。在 Inspector 里直接调用age填28点Run。返回结果应该是4因为 user 表里年龄大于 28 的有 Bob 30、David 35、Grace 31、Ivan 29共 4 个。如果返回 0 或者报错说明数据库连接有问题回到第 1 节检查数据是否真的插进去了。Inspector 验证通过后回到 Cursor。把对话模式切到 Agent 模式快捷键CtrlI或者点输入框旁边的模式切换然后直接问“帮我查一下 user 表里年龄大于 28 的有几个人”。Cursor 会自动调用mysqlmcp的analysis_data工具传入age28然后把结果返回给你。第一次调用可能会弹一个确认框点允许就行。成功的话你会看到 Cursor 的回复里包含“4 个”或者“4 人”并且工具调用记录里显示analysis_data(age28)。这就说明整条链路通了Cursor Agent → MCP 协议 → Fastmcp Server → pymysql → 本地 MySQL。如果 Cursor 里问的时候没反应检查 MCP 面板里mysqlmcp是不是绿色。灰色或者红色说明启动失败点开看错误日志。常见的是路径写错或者 conda 环境没激活。Cursor 启动 MCP 时不会自动激活 conda 环境所以command必须指向环境里的 python.exe 绝对路径不能写python。5. 本篇常见报错排查401、local proxy failed 与 reading choices报错一pymysql.err.OperationalError: (1045, Access denied for user rootlocalhost)。这是密码错了。检查mysql.py里的password字段和你mysql -u root -p登录时输入的密码一致。如果密码里有特殊字符比如或#在 Python 字符串里不用转义直接写就行。报错二ModuleNotFoundError: No module named fastmcp。这是环境不对。Cursor 启动 MCP 时用的 python 不是你激活的 conda 环境。检查mcp.json里的command路径必须是envs\mysqlmcp\python.exe不能是 base 环境的 python。用where python在激活环境后确认路径。报错三local proxy failed或者MCP error -32000: Connection closed。这是 Cursor 启动 MCP Server 后进程立刻退出了。原因通常是脚本里有语法错误或者mcp.run()之前有print输出污染了 stdio。把mysql.py里的print全删掉只保留mcp.run()。另外确认if __name__ __main__:这行没写错缩进要对。报错四reading choices或Unexpected token之类的 JSON 解析错误。这是 MCP 返回的内容不是合法 JSON。检查analysis_data的返回类型必须是int、str、dict这些可序列化的类型。如果返回了cursor对象或者conn对象Fastmcp 序列化时会失败。确保return result返回的是fetchone()[0]这个整数。报错五OAuth相关错误。MCP 本身不走 OAuth如果你在 Cursor 里看到 OAuth 报错说明你配的不是 MCP Server 而是模型 API。检查mcp.json的格式mcpServers下面不应该有apiKey或baseUrl字段那些是模型配置。MCP 只需要command和args。报错六Inspector 打不开或者npx卡住。这是 Node.js 版本太低。升级到 18 以上node --version确认。如果npx下载慢可以先用npm install -g modelcontextprotocol/inspector全局装然后直接跑mcp-inspector命令。报错七MySQL 服务没启动。Windows 下services.msc里找 MySQL 服务状态是“正在运行”才行。如果停了右键启动。端口被占用的话netstat -ano | findstr 3306看谁占了改 MySQL 端口或者杀掉进程。排查顺序建议先手动python mysql.py确认脚本能跑再用 Inspector 确认工具能调最后在 Cursor 里问。每一步过了再走下一步不要跳步。跳步的话报错信息会混在一起很难定位。6. 把本地数据接进 Agent 的下一步链路跑通后你可以把analysis_data换成更复杂的查询比如按名字模糊搜索、按年龄区间统计、多表关联。Fastmcp 支持多个mcp.tool()函数每个函数就是一个独立工具Agent 会根据你的问题自动选合适的工具调用。连接参数建议抽成环境变量不要硬编码在脚本里。用os.environ.get(MYSQL_PASSWORD)读取然后在 Cursor 的mcp.json里加env字段传入。这样脚本可以提交到 Git密码不会泄露。{ mcpServers: { mysqlmcp: { command: C:\\Users\\你的用户名\\miniconda3\\envs\\mysqlmcp\\python.exe, args: [E:\\projects\\mysql.py], env: { MYSQL_PASSWORD: 你的密码 } } } }如果你想让 Agent 长期跑查询任务比如定时统计或者批量分析可以考虑用 Coding Plan 把 MCP 服务和模型调用串起来。模型对话页面可以单独验证analysis_data的返回是否符合预期接入文档里有 MCP 协议的详细说明和更多客户端配置示例。API Keys 页面管理你的调用凭证注意 MCP 配置本身不需要 KeyKey 是模型调用才用的。本地 MySQL 的数据敏感的话别把生产库直接接进来。建一个只读账号只授权SELECT权限GRANT SELECT ON mcp.* TO readonlylocalhost IDENTIFIED BY 密码;然后mysql.py里用这个账号连。这样即使 Agent 调用了不该调的工具也改不了数据。最后提醒一点Cursor 的 MCP 配置改完后必须重启 Cursor 才生效热重载不支持。改mysql.py后也要重启 MCP Server在 Cursor 的 MCP 面板里点刷新或者重启按钮。Inspector 那边每次改脚本都要重新跑命令它不会自动重载。