# MySQL MCP 服务器安装配置指南
本文档记录了在 Windows 系统上为 Claude Code 配置 MySQL MCP 服务器的完整步骤和遇到的问题解决方案。
## 环境要求
– Windows 10/11
– Claude Code 已安装
– 有管理员权限（用于安装软件）
## 一、安装 uv 工具
`uvx` 是运行 Python 工具的命令，需要先安装 `uv` 包管理器。
### 1.1 安装步骤
打开 **PowerShell**（注意：不是 CMD 也不是 Git Bash），执行：
“`powershell
powershell -ExecutionPolicy ByPass -c “irm https://astral.sh/uv/install.ps1 | iex”
“`
### 1.2 安装位置
默认安装路径：`C:\Users\你的用户名\.local\bin`
安装完成后会看到以下文件：
– `uv.exe`
– `uvx.exe`
– `uvw.exe`
### 1.3 常见问题
**问题1：安装超时**
– 原因：网络问题或下载慢
– 解决：等待完成或使用代理，必要时重试
**问题2：安装后找不到命令**
– 原因：PATH 环境变量未生效
– 解决：需要使用完整路径或配置 PATH（见下文）
## 二、配置 ~/.claude.json
### 2.1 找到配置文件位置
Windows 系统中，该文件位于：`C:\Users\你的用户名\.claude.json`
### 2.2 修改配置文件
用文本编辑器（推荐 VSCode 或 Notepad++）打开该文件，在文件开头添加 `mcpServers` 配置。
**注意 JSON 格式：**
“`json
{
“numStartups”: 94,
“mcpServers”: {
“filesystem”: {
“command”: “npx”,
“args”: [“-y”, “@modelcontextprotocol/server-filesystem”, “D:/work/wamp/www/php”],
“env”: {}
},
“github”: {
“command”: “npx”,
“args”: [“-y”, “@modelcontextprotocol/server-github”],
“env”: {}
},
“mysql-charging-parent”: {
“command”: “C:\\Users\\你的用户名\\.local\\bin\\uvx.exe”,
“args”: [“mysqldb-mcp-server”],
“env”: {
“MYSQL_HOST”: “10.180.3.2”,
“MYSQL_USER”: “test”,
“MYSQL_PASSWORD”: “你的数据库密码”,
“MYSQL_DATABASE”: “你的数据库名”,
“MYSQL_PORT”: “3306”,
“MYSQL_READONLY”: “false”
}
}
},
“installMethod”: “global”,
“autoUpdates”: true,
…其他配置…
}
“`
### 2.3 配置要点
**关键点1：使用完整路径**
– ❌ 错误：`”command”: “uvx”`
– ✅ 正确：`”command”: “C:\\Users\\你的用户名\\.local\\bin\\uvx.exe”`
**关键点2：路径中的反斜杠要转义**
– Windows 路径需要使用双反斜杠：`\\`
– 或使用正斜杠：`/`（JSON 中也可以）
**关键点3：mcpServers 位置**
– `mcpServers` 应该作为顶层字段
– 与 `numStartups`、`installMethod` 等平级
– 不要多加 `{` 或少加逗号 `,`
**关键点4：数据库配置**
– `MYSQL_READONLY`: `”false”` 允许写操作，`”true”` 只读
– 每个项目可以配置独立的数据库连接
– 服务器名称（如 `mysql-charging-parent`）可自定义，建议用项目名
### 2.4 常见 JSON 格式错误
**错误示例1：多余的大括号**
“`json
{
“numStartups”: 94,
{ // ❌ 这里多了一个 {
“mcpServers”: {
“`
**错误示例2：缺少逗号**
“`json
{
“mcpServers”: {
…
} // ❌ 这里缺少逗号
“installMethod”: “global”
}
“`
**正确格式：**
“`json
{
“mcpServers”: {
…
}, // ✅ 注意这里的逗号
“installMethod”: “global”
}
“`
## 三、配置项目环境变量（可选）
如果希望在项目内部也能使用 `uvx` 命令（用于 bash 操作），需要配置项目的 `.claude/settings.local.json`：
“`json
{
“env”: {
“PATH”: “C:\\Users\\你的用户名\\.local\\bin;${PATH}”
},
“permissions”: {
…现有权限配置…
}
}
“`
## 四、验证配置
### 4.1 重启 Claude Code
**重要：必须完全重启应用，不是重开终端窗口！**
1. 按 `Ctrl + Q` 或关闭所有 Claude Code 窗口
2. 重新启动 Claude Code
### 4.2 验证 MCP 服务器
在终端中执行：
“`bash
claude mcp list
“`
**成功标志：**
“`
Checking MCP server health…
filesystem: npx -y @modelcontextprotocol/server-filesystem D:/work/wamp/www/php – ✓ Connected
github: npx -y @modelcontextprotocol/server-github – ✓ Connected
mysql-charging-parent: C:\Users\…\uvx.exe mysqldb-mcp-server – ✓ Connected
“`
### 4.3 测试数据库查询
可以让 Claude Code 执行查询测试：
“`
请查询 orders 表的最新 2 条记录
“`
## 五、常见问题排查
### 问题1：mysql-charging-parent 显示 ✗ Failed to connect
**原因A：uvx 路径错误**
– 检查：在终端执行 `C:\Users\你的用户名\.local\bin\uvx.exe –version`
– 解决：确认路径正确，更正 `.claude.json` 中的 `command` 字段
**原因B：数据库连接信息错误**
– 检查：HOST、USER、PASSWORD、DATABASE、PORT 是否正确
– 解决：更正 `env` 中的配置信息
**原因C：网络问题**
– 检查：数据库服务器是否可访问
– 解决：测试网络连通性，检查防火墙设置
### 问题2：配置文件修改后不生效
**解决步骤：**
1. 确认 JSON 格式正确（可用 JSON 校验工具检查）
2. 完全关闭 Claude Code（不是隐藏窗口）
3. 重新启动 Claude Code
4. 再次执行 `claude mcp list`
### 问题3：JSON 格式验证
使用在线工具验证 JSON 格式：
– https://jsonlint.com/
– 或在 VSCode 中打开文件会自动检查格式
### 问题4：Command not found: uvx
**原因：PATH 未生效或 uv 未安装成功**
**解决步骤：**
1. 测试 uvx 是否存在：
“`bash
ls C:\Users\你的用户名\.local\bin\
“`
2. 如果文件存在但命令找不到，使用完整路径
3. 如果文件不存在，重新安装 uv
## 六、完整配置检查清单
安装完成后，请检查：
– [ ] `uv` 已成功安装到 `C:\Users\你的用户名\.local\bin\`
– [ ] `~/.claude.json` 中添加了 `mcpServers` 配置
– [ ] `command` 使用了完整路径（包含 `.exe` 后缀）
– [ ] 数据库连接信息正确（HOST、USER、PASSWORD、DATABASE、PORT）
– [ ] JSON 格式正确（括号、逗号、引号都匹配）
– [ ] 已完全重启 Claude Code
– [ ] `claude mcp list` 显示所有服务器 ✓ Connected
– [ ] 可以成功执行数据库查询
## 七、其他项目配置
如需为其他项目配置 MySQL MCP 服务器，只需在 `mcpServers` 中添加新的配置项：
“`json
“mysql-另一个项目名”: {
“command”: “C:\\Users\\你的用户名\\.local\\bin\\uvx.exe”,
“args”: [“mysqldb-mcp-server”],
“env”: {
“MYSQL_HOST”: “localhost”,
“MYSQL_USER”: “root”,
“MYSQL_PASSWORD”: “另一个密码”,
“MYSQL_DATABASE”: “另一个数据库”,
“MYSQL_PORT”: “3306”,
“MYSQL_READONLY”: “false”
}
}
“`
然后在对应项目的 `CLAUDE.md` 中注明使用的 MCP 服务器名称。
## 八、参考资料
– uv 官方文档：https://github.com/astral-sh/uv
– mysqldb-mcp-server：Python 包，通过 uvx 自动安装
– Claude Code MCP 文档：https://docs.claude.com/en/docs/claude-code
—
**安装完成日期：** 2025-09-30
**配置人员：** Claude Code
**测试状态：** ✅ 已验证成功
近期评论