【claude code】MySQL MCP 配置完整指南

Claude Code + MySQL MCP 配置完整指南

一、背景和目标

目标是让 Claude Code 能直接读取 MySQL 数据库，结合项目代码一起分析，不需要每次手动提供连接信息。

二、环境准备

Node.js 是基础，Claude Code 和 MCP 包都依赖它运行，类似 .NET 项目需要 .NET Runtime。

powershell 复制代码

# 验证是否安装
node --version
npm --version

安装依赖包：

powershell 复制代码

cd C:\Users\dell\Desktop\claude-md
npm init -y
npm install @modelcontextprotocol/sdk mysql2

三、踩坑过程

坑1：第三方 MCP 包全部失败

最初想直接用现成的包，省去开发：

包	失败原因
`@modelcontextprotocol/server-mysql`	npm 404，已下架
`@benborla29/mcp-server-mysql`	缺少 `es-errors` 模块，不兼容 Node.js v24
`mcp-mysql-server`	能启动，但必须手动调用 `connect_db` 传参数，DeepSeek 不会主动调用，一直问连接信息

教训： npm 上的第三方 MCP 包质量参差不齐，版本兼容性是大问题，不如自己写。

坑2：手动实现 MCP 协议失败

第一版自己实现了 MCP 协议（Content-Length 解析、JSON-RPC 处理），单独测试握手没问题，但 Claude Code 启动时连接超时 30 秒。

原因：手动实现的协议解析在 Claude Code 实际调用时有细微差异，导致握手失败。

教训： 不要自己实现 MCP 协议，用官方 SDK。

坑3：MCP 配置作用域问题

最初用 -s local 配置：

powershell 复制代码

claude mcp add --transport stdio mysql -s local -- ...

结果换项目后 MCP 就消失了，因为 -s local 是项目级别配置，只在当前项目目录下生效。

解决： 改用 -s user，写入用户级别配置文件 C:\Users\dell\.claude.json，所有项目都能用：

powershell 复制代码

claude mcp add --transport stdio mysql -s user -- ...

坑4：node 路径问题

直接用 node 命令配置 MCP，Claude Code 找不到：

powershell 复制代码

claude mcp add ... -- node mysql-mcp-server.js  # 失败

解决： 用 node 的完整路径：

powershell 复制代码

where.exe node  # 找到路径：C:\Program Files\nodejs\node.exe
claude mcp add ... -- "C:\Program Files\nodejs\node.exe" "C:\Users\dell\Desktop\claude-md\mysql-mcp-server.js"

坑5：代理问题

直接在终端运行 claude 连不上 api.anthropic.com，报 ERR_BAD_REQUEST。

解决： 写入 PowerShell 启动脚本，每次启动自动设置代理：

powershell 复制代码

$env:https_proxy="http://127.0.0.1:7890"
$env:http_proxy="http://127.0.0.1:7890"

坑6：DeepSeek 模型不会主动调用 MCP

配置好 MCP 后，DeepSeek 模型不知道有工具可用，一直在项目文件里找数据库连接信息。

解决： 在 CLAUDE.md 里明确说明：

markdown 复制代码

## 数据库连接（重要）
项目配置文件中的连接字符串是占位符，不要使用。
查询数据库必须使用已配置的 MCP 工具：
- mysql：支持 test/prod 两个库，直接调用工具即可
禁止使用项目文件中的任何连接字符串。

四、最终方案

文件结构

复制代码

C:\Users\dell\Desktop\claude-md\
├── mysql-mcp-server.js    # 自写 MCP 服务（核心）
├── node_modules\           # 依赖包
├── package.json
├── tms-server.md          # 各项目的 CLAUDE.md 模板
├── tms-client.md
└── ...

MCP 服务支持的工具

工具	作用
`query`	执行 SELECT/SHOW/DESCRIBE/EXPLAIN
`list_tables`	列出所有表
`describe_table`	查看表结构和字段
`show_indexes`	查看索引信息
`switch_db`	切换 test/prod 库
`current_db`	查看当前使用的库

MCP 注册命令

powershell 复制代码

claude mcp add --transport stdio mysql -s user -- "C:\Program Files\nodejs\node.exe" "C:\Users\dell\Desktop\claude-md\mysql-mcp-server.js"

mysql-mcp-server.js 核心结构

javascript 复制代码

// 1. 引入官方 SDK
const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
const mysql = require('mysql2/promise');

// 2. 配置数据库连接（写死在文件里，不对外暴露）
const DB_CONFIG = {
    test: { host, port, user, password, database },
    prod: { host, port, user, password, database }
};

// 3. 注册工具
server.tool('query', '描述', { 参数 }, async ({ 参数 }) => { 执行逻辑 });

// 4. 启动 stdio 传输
const transport = new StdioServerTransport();
await server.connect(transport);

五、启动脚本完整逻辑

复制代码

运行脚本
  → 设置代理环境变量
  → 设置 DeepSeek 模型环境变量
  → 选择项目
  → 选择模型
  → 复制对应 CLAUDE.md 到项目目录（含数据库说明）
  → 启动 Claude Code
  → 退出后删除 CLAUDE.md，保存历史记录到 claude-md 文件夹

启动脚本关键片段

powershell 复制代码

# 代理
$env:https_proxy="http://127.0.0.1:7890"
$env:http_proxy="http://127.0.0.1:7890"

# DeepSeek 模型映射
$env:ANTHROPIC_BASE_URL="https://api.deepseek.com"
$env:ANTHROPIC_API_KEY="你的API Key"
$env:ANTHROPIC_MODEL="deepseek-v4-pro[1m]"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-pro[1m]"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-pro[1m]"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-flash"
$env:CLAUDE_CODE_SUBAGENT_MODEL="deepseek-v4-flash"

# 启动和清理
try {
    claude
} finally {
    Remove-Item "$projectPath\CLAUDE.md" -ErrorAction SilentlyContinue
    Remove-Item "$projectPath\.env" -ErrorAction SilentlyContinue
}

六、核心原理

MCP 是什么

Anthropic 制定的标准协议，让 AI 能调用外部工具，类似 USB 接口，符合规范就能接入。不只是 Claude Code，Cursor、Cline 等工具也支持 MCP。

三者分工

复制代码

大模型（DeepSeek/Claude）= 大脑，负责理解和决策
MCP 工具               = 手脚，负责执行具体操作
Claude Code            = 身体，负责协调大脑和手脚

MCP 工作流程

复制代码

Claude Code 启动
  → 读取 .claude.json 配置
  → 启动 MCP 进程（node mysql-mcp-server.js）
  → 握手，获取工具列表
你说话
  → 大模型分析，决定调用哪个工具
  → Claude Code 转发请求给 MCP 进程
  → MCP 执行查询，返回结果
  → 大模型用自然语言回复你

MCP 协议三步骤

握手：MCP 启动后告诉 Claude Code "我准备好了，支持工具调用"
列工具：返回工具列表，Claude Code 汇总给大模型
执行工具：收到调用请求，执行，返回结果

七、常用命令速查

powershell 复制代码

# 查看所有 MCP
claude mcp list

# 查看某个 MCP 状态
claude mcp get mysql

# 删除 MCP
claude mcp remove "mysql" -s user

# 重新添加 MCP
claude mcp add --transport stdio mysql -s user -- "C:\Program Files\nodejs\node.exe" "C:\Users\dell\Desktop\claude-md\mysql-mcp-server.js"

# Claude Code 内部命令
/mcp          # 查看 MCP 连接状态
/doctor       # 诊断问题
/login        # 重新登录
/logout       # 退出登录
/init         # 生成 CLAUDE.md
/clear        # 清除对话上下文
/exit         # 退出 Claude Code