内容
# MySQL MCP Server 🚀
> **v4.0.0** - 全新架构重写，更简洁、更强大！
一个功能强大且易用的 MySQL 数据库 MCP（Model Context Protocol）服务器，支持 AI 助手安全地操作 MySQL 数据库。
## 🌟 核心特性
- 🌐 **StreamableHTTP 协议** - 基于最新 MCP 规范实现
- 🔐 **Header 预配置** - 凭证不暴露给 AI，安全可靠
- 🤖 **AI 动态管理** - AI 可以帮你添加/切换数据库连接
- 🔗 **多数据库支持** - 同时管理多个数据库，随时切换
- 📊 **完整 CRUD** - 支持所有 SQL 操作
- 🏗️ **模块化架构** - 清晰的目录结构，易于扩展
---
## 📦 安装
### 环境要求
- Node.js 18+
- MySQL 5.7+ 或 8.0+
- MCP 客户端（Claude Desktop、Cursor 等）
### 安装步骤
```bash
# 克隆项目
git clone https://github.com/guangxiangdebizi/MySQL_MCP.git
cd MySQL_MCP
# 安装依赖
npm install
# 编译
npm run build
# 启动服务器
npm start
```
---
## ⚙️ 配置方法
### 方式一：Header 预配置（推荐）
编辑 MCP 配置文件：
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`
#### 单数据库配置
```json
{
"mcpServers": {
"mysql-mcp": {
"type": "streamableHttp",
"url": "http://localhost:3001/mcp",
"timeout": 600,
"headers": {
"X-MySQL-Host": "localhost",
"X-MySQL-Port": "3306",
"X-MySQL-User": "root",
"X-MySQL-Password": "your_password",
"X-MySQL-Database": "your_database"
}
}
}
}
```
#### 多数据库配置
```json
{
"mcpServers": {
"mysql-mcp": {
"type": "streamableHttp",
"url": "http://localhost:3001/mcp",
"timeout": 600,
"headers": {
"X-MySQL-Host-1": "prod.mysql.com",
"X-MySQL-User-1": "prod_user",
"X-MySQL-Password-1": "prod_pass",
"X-MySQL-Database-1": "production",
"X-MySQL-Host-2": "test.mysql.com",
"X-MySQL-User-2": "test_user",
"X-MySQL-Password-2": "test_pass",
"X-MySQL-Database-2": "testing"
}
}
}
}
```
**优势：**
- ✅ 数据库凭证不暴露给 AI
- ✅ 启动即连接，无需手动操作
- ✅ 支持多数据库同时连接
### 方式二：AI 动态添加（灵活）
不配置 Header，让 AI 在对话中帮你添加连接：
```json
{
"mcpServers": {
"mysql-mcp": {
"type": "streamableHttp",
"url": "http://localhost:3001/mcp",
"timeout": 600
}
}
}
```
**使用示例：**
```
你: 帮我连接到本地 MySQL，用户名 root，密码 123456，数据库 mydb
AI: [调用 add_connection 工具]
```
---
## 🔧 工具列表
### 连接管理
| 工具名称 | 功能说明 | 使用场景 |
|---------|---------|---------|
| `add_connection` | 添加数据库连接 | AI 帮你动态添加新连接 |
| `list_connections` | 列出所有连接 | 查看当前有哪些数据库 |
| `select_database` | 选择活跃数据库 | 切换到其他数据库 |
| `remove_connection` | 移除连接 | 清理不需要的连接 |
### 查询操作
| 工具名称 | 功能说明 | 使用场景 |
|---------|---------|---------|
| `execute_query` | 执行 SQL | 任何 SQL 操作（SELECT、INSERT、UPDATE、DELETE） |
| `show_tables` | 显示所有表 | 快速了解数据库结构 |
| `describe_table` | 查看表结构 | 查看字段、类型、样本数据 |
| `show_databases` | 显示所有数据库 | 查看可访问的数据库列表 |
---
## 🎮 使用示例
### 场景一：使用 Header 预配置
```
你: 显示所有表
AI: [调用 show_tables]
📊 数据库表列表 (共 5 个表)
1. users
2. orders
3. products
...
你: 查看 users 表的结构
AI: [调用 describe_table，参数：users]
📋 表结构: users
字段信息:
- id (INT, 主键)
- name (VARCHAR)
- email (VARCHAR)
...
```
### 场景二：AI 动态添加连接
```
你: 帮我连接两个数据库：
1. 生产库：prod.mysql.com，用户 admin，密码 xxx，数据库 shop
2. 测试库：test.mysql.com，用户 tester，密码 yyy，数据库 shop_test
AI: [调用 add_connection，参数：id=prod, host=prod.mysql.com...]
[调用 add_connection，参数：id=test, host=test.mysql.com...]
✅ 两个数据库连接已添加
你: 列出所有连接
AI: [调用 list_connections]
📊 当前数据库连接列表 (共 2 个)
🟢 [1] prod
└─ prod.mysql.com:3306/shop
└─ ✅ 当前活跃连接
⚪ [2] test
└─ test.mysql.com:3306/shop_test
你: 切换到测试库
AI: [调用 select_database，参数：test]
✅ 已选择数据库: test
你: 查询用户表前 10 条
AI: [调用 execute_query，SQL: SELECT * FROM users LIMIT 10]
✅ 查询成功，返回 10 行数据
[显示 JSON 格式数据]
```
---
## 🏗️ 项目架构
```
MySQL_MCP/
├── src/
│ ├── index.ts # 主入口（HTTP Server + 会话管理）
│ ├── database.ts # 数据库连接管理器
│ └── tools/ # 工具模块
│ ├── index.ts # 工具统一导出和路由
│ ├── connection.ts # 连接管理工具
│ └── query.ts # 查询工具
├── dist/ # 编译后的 JS 文件
├── package.json
├── tsconfig.json
└── README.md
```
**核心设计：**
- **index.ts** - Express HTTP 服务器 + MCP Server 初始化
- **database.ts** - 封装数据库连接池和查询逻辑
- **tools/** - 每个文件负责一类工具的定义和处理
---
## 🔒 安全建议
### 数据库权限配置
为 MCP 创建专用数据库用户，限制权限：
```sql
-- 创建专用用户
CREATE USER 'mcp_user'@'%' IDENTIFIED BY 'strong_password';
-- 授予必要权限
GRANT SELECT, INSERT, UPDATE, DELETE ON your_database.* TO 'mcp_user'@'%';
-- 生产环境只读用户
GRANT SELECT ON your_database.* TO 'mcp_readonly'@'%';
```
### HTTP 模式安全
- ✅ 使用 Header 预配置，避免凭证暴露给 AI
- ✅ 生产环境使用 HTTPS（Nginx 反向代理）
- ✅ 限制访问 IP（防火墙规则）
- ✅ 定期更新数据库密码
- ✅ 监控日志，发现异常访问
---
## 🚀 NPM 脚本
```bash
# 开发模式（TypeScript 直接运行）
npm run dev
# 编译
npm run build
# 生产模式（运行编译后的 JS）
npm start
# 全局安装
npm run install-global
```
---
## 📝 环境变量
创建 `.env` 文件（可选）：
```env
# HTTP 服务器端口
PORT=3001
# Node 环境
NODE_ENV=production
```
---
## ❗ 常见问题
### 1. 端口被占用
**错误：** `EADDRINUSE: address already in use :::3001`
**解决：** 修改 `.env` 文件中的 `PORT`，或终止占用进程
```bash
# Windows
netstat -ano | findstr :3001
taskkill /F /PID <PID>
# Linux/Mac
lsof -ti:3001 | xargs kill -9
```
### 2. 连接失败
**错误：** `数据库连接失败`
**检查：**
- MySQL 服务是否运行
- 主机、端口、用户名、密码是否正确
- 防火墙是否允许连接
### 3. 会话丢失
**问题：** 重启服务器后提示 "Session not found"
**原因：** 会话存储在内存中，重启后清空
**解决：** 刷新 MCP 客户端（重新初始化）
### 4. 连接已关闭错误
**错误：** `Can't add new command when connection is in closed state`
**原因：**
- 数据库连接长时间空闲，MySQL 服务器关闭了连接
- 网络中断导致连接断开
**解决方案：**
- ✅ v4.0.5+ 已使用连接池替代单连接，自动支持：
- 连接保活（Keep-Alive）机制
- 自动重连功能
- 并发查询支持
- 如果仍遇到问题，请重启 MCP 服务器
---
## 📦 版本历史
### v4.0.5 (2025-12-09) - 连接池优化
- 🎯 使用连接池替代单连接
- 🔄 自动连接保活（Keep-Alive）
- 🔌 自动重连机制
- 🚀 支持并发查询
- 🐛 修复 "connection in closed state" 错误
### v4.0.0 (2025-12-09) - 全新架构
- 🔥 完全重写，全新模块化架构
- ✨ 基于最新 MCP StreamableHTTP 协议
- 🎯 简化工具：连接管理 + 查询操作
- 🏗️ 清晰的目录结构：`tools/` 模块化
- 🚀 更快的响应速度
- 📖 更清晰的代码注释
### v3.x - 旧版本
- 支持事务管理、回滚等复杂功能
- 较为复杂的架构
---
## 📞 支持与反馈
- 🐛 **问题报告**: [GitHub Issues](https://github.com/guangxiangdebizi/MySQL_MCP/issues)
- 💡 **功能建议**: [GitHub Discussions](https://github.com/guangxiangdebizi/MySQL_MCP/discussions)
- 📧 **联系作者**: guangxiangdebizi@gmail.com
---
## 🔧 故障排除
### 问题：`ERR_MODULE_NOT_FOUND` 错误
**错误信息**：
```
Error [ERR_MODULE_NOT_FOUND]: Cannot find module '...@modelcontextprotocol/sdk...'
```
**解决方案**：
1. **删除并重新安装依赖**：
```bash
# 删除旧依赖
rm -rf node_modules package-lock.json # Linux/Mac
# 或
rmdir /s /q node_modules && del package-lock.json # Windows
# 清理缓存
npm cache clean --force
# 重新安装
npm install
```
2. **检查 Node.js 版本**：
```bash
node --version # 需要 >= 18.0.0
```
3. **使用全局安装**：
```bash
npm install -g @xingyuchen/mysql-mcp-server@latest
```
### 问题：SSE 流断开
**错误信息**：
```
SSE stream disconnected: TypeError: terminated
```
**解决方案**：
在 `mcp.json` 中设置更长的超时或禁用超时：
```json
{
"mysql-mcp-http": {
"type": "streamableHttp",
"url": "http://localhost:3002/mcp",
"timeout": 0, // 0 表示无超时限制
"headers": { ... }
}
}
```
### 问题：安全漏洞警告
**警告信息**：
```
npm audit: vulnerabilities found
```
**解决方案**：
```bash
# 自动修复
npm audit fix
# 如果还有问题，强制修复
npm audit fix --force
# 重新构建
npm run build
```
### 问题：端口被占用
**错误信息**：
```
Error: listen EADDRINUSE: address already in use :::3002
```
**解决方案**：
1. **更改端口**（在 `.env` 文件中）：
```env
PORT=3003
```
2. **或者关闭占用端口的进程**：
```bash
# Windows
netstat -ano | findstr :3002
taskkill /PID <进程ID> /F
# Linux/Mac
lsof -i :3002
kill -9 <进程ID>
```
### 获取更多帮助
- 🐛 [提交 Issue](https://github.com/guangxiangdebizi/MySQL_MCP/issues)
- 📖 [查看文档](https://github.com/guangxiangdebizi/MySQL_MCP#readme)
- 💬 [讨论区](https://github.com/guangxiangdebizi/MySQL_MCP/discussions)
---
## 📄 License
Apache 2.0 License - 详见 [LICENSE](./LICENSE) 文件
---
**⭐ 如果这个项目对你有帮助，请给个 Star 支持一下！**
