MCP 安装与使用：在 Claude Code 中用自然语言操作 MySQL

1. 为什么 Claude Code 需要 MCP 才能操作 MySQLClaude Code 本身是一个跑在终端里的编码助手它能读写文件、执行命令、理解项目结构但它默认碰不到你的数据库。你问它「employee 表里有多少在职员工」它只能给你一段 SQL 让你自己去客户端跑然后把结果复制回来给它分析。这个来回粘贴的过程就是效率损耗最大的地方。MCPModel Context Protocol解决的就是这个「能说不能做」的问题。你可以把它理解成 AI 世界的 USB-C 接口以前每个工具都要单独适配现在只要工具实现了 MCP ServerClaude Code 就能通过统一协议调用它。MySQL MCP Server 就是这样一个适配器——它对外暴露「列出所有表」「描述表结构」「执行查询」「插入数据」「导出结果」等工具Claude Code 在对话中自动决定调用哪个工具、传什么参数。这篇教程聚焦一个最小闭环装好 MySQL MCP Server配好连接参数在 Claude Code 里用一句自然语言完成「查表结构 → 查询数据 → 插入数据 → 导出文件」的完整链路。适合已经装好 Claude Code CLI、手头有 MySQL 5.7 实例、想在终端里直接对数据库说话的人。读完你不需要打开 Navicat 或 DBeaver所有操作都在 Claude Code 对话里完成。2. 前置准备Node.js、Claude Code 与 MySQL 三件套在写任何配置之前先把三个依赖确认到位。MCP Server 本质是一个独立进程Claude Code 负责拉起它它负责连 MySQL所以三者缺一不可。依赖最低版本验证命令作用Node.js≥ 18node -v运行 MCP Server 的运行时Claude Code最新版claude --version发起 MCP 调用的客户端MySQL5.7推荐 8.0mysql --version被操作的目标数据库Node.js 低于 18 会在启动 MCP Server 时报语法或模块错误先升级再继续。Claude Code 如果版本太旧/mcp命令可能不存在用npm update -g anthropic-ai/claude-code更新。MySQL 这边确认服务在跑macOS 用brew services list看 mysql 状态Linux 用systemctl status mysqlWindows 在服务管理器里确认 MySQL 服务已启动。另外准备一个数据库账号。强烈建议不要用 root 跑 MCP后面安全章节会展开。先在 MySQL 里建一个专用账号只给需要的库和权限CREATE USER mcp_userlocalhost IDENTIFIED BY your_strong_password; GRANT SELECT, INSERT, UPDATE ON your_database.* TO mcp_userlocalhost; FLUSH PRIVILEGES;如果只是查询场景把INSERT, UPDATE去掉只留SELECT。这一步做完后面配置里的账号密码就用这个不要用 root。3. 安装 MySQL MCP Server 的四种方式社区里维护得比较活跃的 MySQL MCP 包是pickstar-2002/mysql-mcp提供约 15 个数据库工具覆盖列库表、描述结构、查询、插入、导出等常见操作。安装方式有四种按场景选。3.1 命令行添加最快捷Claude Code 自带mcp add子命令一条命令写完配置claude mcp add mysql-mcp \ -e MYSQL_HOSTlocalhost \ -e MYSQL_PORT3306 \ -e MYSQL_USERmcp_user \ -e MYSQL_PASSWORDyour_strong_password \ -e MYSQL_DATABASEyour_database \ -- npx -y pickstar-2002/mysql-mcplatest参数拆解mysql-mcp是服务器名称可自定义每个-e KEYVALUE是一个环境变量对应一个连接参数--是分隔符后面跟启动 MCP Server 的实际命令npx -y表示自动下载并运行-y跳过确认。默认写入项目作用域的.mcp.json只对当前项目生效。想对所有项目生效加-s user配置会写到用户目录的 settings.json。注意项目作用域下密码会明文写进.mcp.json。务必把.mcp.json加进.gitignore否则密码会进版本库。3.2 手动编辑配置文件想对照教程逐项检查直接编辑文件更直观。项目根目录建.mcp.json或全局~/.claude/settings.jsonWindows 是%USERPROFILE%\.claude\settings.json的mcpServers字段里加{ mcpServers: { mysql-mcp: { command: npx, args: [-y, pickstar-2002/mysql-mcplatest], env: { MYSQL_HOST: localhost, MYSQL_PORT: 3306, MYSQL_USER: mcp_user, MYSQL_PASSWORD: your_strong_password, MYSQL_DATABASE: your_database } } } }JSON 格式对逗号和引号很敏感写完用node -e JSON.parse(require(fs).readFileSync(.mcp.json))验证一下能不能解析比等到 Claude Code 报错再回头查快得多。3.3 npm 本地安装npx每次启动都要检查包版本网络不好时首次可能等 1030 秒。想固定版本、减少等待先装到本地npm install -g pickstar-2002/mysql-mcp然后把配置里的command改成mysql-mcp如果全局 bin 在 PATH 里或改成node加args指向npm root -g下的入口文件。这样启动时不再拉包适合网络不稳定或需要锁定版本的团队。3.4 让 CLI 自己装第一次接触 MCP 时可以直接在 Claude Code 里说「帮我添加一个连接本地 MySQL 的 MCP库名是 your_database」。CLI 会引导你补全参数并写入配置。这种方式上手快但熟练后建议回到方式一或方式二因为命令行和文件配置可复现、可版本管理、方便团队共享。4. 验证连接/mcp 状态与自然语言测试配置写完必须重启 Claude CodeMCP Server 是在启动时加载的热改配置不生效。重启后进入项目目录启动claude输入/mcp。正常情况会列出mysql-mcp状态显示为已连接展开能看到它暴露的工具列表。如果显示红色或错误说明 Server 启动失败先别急着在 Claude Code 里试回到本机终端手动跑一次MYSQL_HOSTlocalhost MYSQL_PORT3306 MYSQL_USERmcp_user \ MYSQL_PASSWORDyour_strong_password MYSQL_DATABASEyour_database \ npx -y pickstar-2002/mysql-mcplatest终端会直接打印报错常见的是密码错误、MySQL 没启动、库名不存在。把这里的报错解决掉Claude Code 里的红色状态自然消失。状态正常后用自然语言做第一次测试。在 Claude Code 里输入列出当前数据库里所有表Claude Code 会自动调用mysql_list_tables工具返回表名列表。再试一句描述 employee 表的结构它会调用mysql_describe_table返回字段名、类型、是否可空、键信息。这两句能跑通说明 MCP 链路已经通了。5. 实战自然语言完成查询、插入与导出以员工管理系统为例走一遍完整操作。假设库里有employee表字段包括id、name、department、status。5.1 查询各部门在职员工数量对 Claude Code 说查询各部门在职员工数量按数量降序排列它会生成类似这样的 SQL 并执行SELECT department, COUNT(*) AS cnt FROM employee WHERE status active GROUP BY department ORDER BY cnt DESC;返回结果直接以表格形式展示在对话里。你不需要打开客户端、不需要手写 SQL、不需要复制结果再粘贴回来分析。如果想让 AI 顺带分析加一句「并简要分析哪个部门人力最紧张」它会在结果基础上给出判断。5.2 插入一条测试数据在 employee 表插入一条测试数据name 为张三department 为技术部status 为 activeClaude Code 调用mysql_insert工具构造 INSERT 语句执行然后反馈影响行数。插入前它会先确认表结构避免字段类型不匹配。如果表有自增主键不需要你指定 id。5.3 导出查询结果到文件把刚才的部门人数查询结果导出成 CSV 文件它会调用mysql_export_data把结果写到本地文件通常在当前项目目录下。导出路径会在对话里告诉你直接打开就能用。5.4 前后对比以「查询各部门在职员工数量」为例没有 MCP 的流程是打开客户端 → 输入密码 → 选库 → 写 SQL → 执行 → 复制结果 → 粘贴给 AI → 等分析七步里五步是人工中转。有 MCP 之后一句话AI 直接返回结果加分析。省掉的不是 AI 的思考时间是你和工具之间的搬运时间。6. 常见报错与排查清单6.1 /mcp 里看不到 mysql-mcp先检查 JSON 格式逗号、引号、括号是否匹配。用node -e解析一遍最快。然后确认 Claude Code 已重启。如果/mcp里显示红色按第 4 节的方法在本机终端单独启动 MCP Server看真实报错。多数情况是环境变量拼写错误或 MySQL 连不上。6.2 npx 首次启动特别慢首次运行要下载包1030 秒正常。网络不佳时按 3.3 节全局安装把配置里的启动命令改成指向本地已安装的入口后续启动就是毫秒级。6.3 连接数据库失败现象排查方向Connection refusedMySQL 没启动macOS 用brew services start mysqlLinux 用systemctl start mysqlAccess denied账号密码不对或该账号没有从 localhost 连接的权限Unknown databaseMYSQL_DATABASE拼写错误或库不存在Docker 容器内连宿主机主机名用host.docker.internal代替localhost视 Docker 版本而定6.4 工具调用报权限错误MCP 账号权限不足。回到 MySQL 里检查GRANT语句确认对目标库有对应操作权限。只查询的场景不需要 INSERT/UPDATE 权限但查询本身需要 SELECT。6.5 如何移除 MCP 配置命令行方式claude mcp remove mysql-mcp名称与添加时一致。手动方式编辑.mcp.json或settings.json删掉mcpServers下对应条目重启 Claude Code。7. 安全配置最小权限与密码保护MCP 让 AI 能直接操作数据库权限给大了风险就大。默认按最小权限配。账号层面不要用 root。为 MCP 单独建账号只授予必要库的必要权限。生产环境优先只读账号只给 SELECT避免 AI 误判场景执行了 DELETE 或 UPDATE。开发环境如果确实需要写入给 SELECT、INSERT、UPDATE不给 DELETE 和 DROP。密码层面.mcp.json不要提交到 Git.gitignore里加上它。优先用 user 作用域把含密码的配置放在用户目录而非项目仓库。团队共享时只提交脱敏模板密码位置用占位符每人本地填真实值。网络层面配置里优先用localhost不要把 MySQL 暴露到公网。需要连远程库时走 SSH 隧道不要直接对公网开放 3306 端口。提示如果团队多人共用一台开发机user 作用域下的配置对所有项目生效注意别把生产库的连接信息配进去。8. 接入 TaoToken 让 MCP 调用更稳定Claude Code 通过 MCP 操作 MySQL 时模型侧的推理请求需要走一个稳定的 API 入口。TaoToken 提供兼容的 API 接入把 Claude Code 的模型请求指向它可以减少网络抖动导致的工具调用中断。配置方式是在 Claude Code 的环境变量里设置 API 地址。先到 TaoToken API Keys 页面 生成一个 Key然后在终端里导出export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYyour_taotoken_keyWindows PowerShell 用$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api。设置完重启 Claude Code/mcp状态正常后模型请求就走 TaoToken 了。如果只是验证 MCP 工具调用是否正常可以在 模型对话页面 先测一句自然语言查询确认模型侧响应正常再回到 Claude Code 里跑完整链路。长期在终端里做编码和 Agent 任务的话Coding Plan 的额度模型更适合高频调用场景。接入文档在 TaoToken 文档里面有各客户端的详细配置示例。Claude Code 专用的接入说明在 ClaudeCodeAnthropic 配置页照着填环境变量即可。配好之后MCP 链路和模型链路都稳定了自然语言操作 MySQL 的体验才完整。我试过在同一个会话里连续做「查结构 → 改数据 → 导出」中间没有一次因为网络问题导致工具调用失败这个稳定性对日常开发很关键。