MySQL MCP Server 🚀

一个功能强大的MySQL数据库MCP（Model Context Protocol）服务器，让你的AI助手可以安全地连接和查询MySQL数据库。

🎯 目标用户: 希望在VSCode的Cline中使用AI助手操作MySQL数据库的开发者

📖 目录

🌟 功能特性
☁️ Smithery云部署
🛠️ 安装教程
⚙️ 配置方法
🎮 使用指南
🔧 高级配置
❗ 故障排除
💡 使用技巧
🔒 安全说明
📋 常见问题

🌟 功能特性

✨ 核心功能

🔗 智能数据库连接: 支持动态连接MySQL数据库，参数灵活配置
🔍 安全查询执行: 仅支持SELECT查询，自动过滤危险操作
📊 表结构查看: 快速查看数据库表列表和详细结构
🛡️ 内置安全防护: SQL注入防护和危险操作过滤
🚀 双模式部署: 支持stdio模式和HTTP/SSE模式

🎯 使用场景

✅ 在AI对话中查询数据库数据
✅ 快速了解数据库表结构
✅ 让AI助手帮你分析数据
✅ 生成数据报告和见解
✅ 数据库内容搜索和过滤

☁️ Smithery云部署

🚀 快速部署到Smithery

Smithery 是专门为MCP服务器设计的云平台，可以一键部署您的MySQL MCP Server。

📋 部署前准备

确保您的项目包含以下文件：

✅ Dockerfile - Docker容器构建配置
✅ smithery.yaml - Smithery平台配置
✅ 完整的项目源码

🔧 部署步骤

Fork项目到您的GitHub

# 访问项目页面并点击Fork按钮
https://github.com/guangxiangdebizi/MySQL_MCP

登录Smithery平台
- 访问 Smithery.ai
- 使用GitHub账号登录
连接GitHub仓库
- 点击 "Deploy Server"
- 选择您Fork的 MySQL_MCP 仓库
- 确认部署配置
等待构建完成
- Smithery会自动构建Docker镜像
- 构建过程大约需要2-3分钟

🎯 使用部署的服务器

部署成功后，您可以在任何支持MCP的AI客户端中使用：

{
  "mcpServers": {
    "mysql-database": {
      "url": "https://server.smithery.ai/your-server-id/sse",
      "type": "sse"
    }
  }
}

💡 云部署优势

🌐 全球访问: 无需本地安装，任何地方都能使用
🔄 自动更新: 推送代码后自动重新部署
📈 高可用性: 专业的云基础设施保障
🔒 安全隔离: 每个部署独立运行，数据安全
📊 使用统计: 详细的调用统计和监控

⚙️ 配置说明

部署后，您需要在AI客户端中提供数据库连接信息：

请帮我连接到MySQL数据库：
- 主机: your-mysql-host.com
- 端口: 3306
- 用户名: your-username
- 密码: your-password
- 数据库: your-database

🔐 安全提示: 建议为MCP服务器创建专门的只读数据库用户，限制权限范围。

🛠️ 安装教程

📋 环境要求

确保你的电脑满足以下要求：

✅ Node.js 18+ - 下载地址
✅ MySQL 5.7+ 或 8.0+ - 确保数据库服务正在运行
✅ VSCode - 下载地址
✅ Cline扩展 - 在VSCode扩展市场搜索"Cline"安装

🔧 一键安装脚本

我们提供了一键安装脚本，帮你自动完成所有安装步骤：

# 下载项目
git clone https://github.com/guangxiangdebizi/MySQL_MCP.git
cd MySQL_MCP

# 运行一键安装脚本
./test-install.bat   # Windows用户
# 或
npm run quick-setup  # 跨平台

📝 手动安装步骤

步骤1: 解决PowerShell权限（Windows用户）

如果遇到执行策略错误，请先运行：

# 在PowerShell中运行（管理员权限）
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

步骤2: 安装项目依赖

# 安装所有依赖包（包括supergateway）
npm install

# 如果安装失败，可以尝试清除缓存
npm cache clean --force
npm install

步骤3: 构建项目

# 编译TypeScript代码
npm run build

# 验证构建是否成功
ls dist/  # 应该能看到index.js文件

⚙️ 配置方法

🎯 配置方式选择

我们提供了两种配置方式，根据你的需求选择：

配置方式	优点	缺点	推荐场景
stdio模式	简单、直接、无需端口	每次重启VSCode需要重新启动	个人开发、简单使用
HTTP/SSE模式	服务持久运行、支持autoApprove	需要管理端口、稍微复杂	频繁使用、团队协作

📌 方法1: stdio模式配置（推荐新手）

步骤1: 打开Cline配置

打开VSCode
按 Ctrl+Shift+P (Windows) 或 Cmd+Shift+P (Mac)
输入 Cline: Open MCP Settings
回车打开配置文件

步骤2: 添加配置

将以下配置复制到Cline设置中：

{
  "mcpServers": {
    "mysql-database": {
      "command": "node",
      "args": ["C:/Users/你的用户名/Desktop/my-awesome-mcp/dist/index.js"],
      "env": {}
    }
  }
}

⚠️ 重要: 请将路径中的 你的用户名 替换为你的实际用户名！

步骤3: 重启VSCode

保存配置后，重启VSCode，配置即生效。

🌐 方法2: HTTP/SSE模式配置（推荐高级用户）

步骤1: 启动Gateway服务

# 启动HTTP/SSE服务
npm run start-gateway

# 服务启动后会显示：
# ✅ MySQL MCP Server running on http://localhost:3100

步骤2: 配置Cline

{
  "mcpServers": {
    "mysql-database": {
      "url": "http://localhost:3100/sse",
      "type": "sse",
      "disabled": false,
      "autoApprove": [
        "connect_database",
        "execute_query",
        "show_tables",
        "describe_table",
        "disconnect_database"
      ]
    }
  }
}

步骤3: 重启VSCode

配置完成后重启VSCode。

🔄 验证配置是否成功

配置成功后，在Cline对话中输入：

你好，请显示一下当前可用的数据库工具

如果配置成功，Cline会显示以下工具：

✅ connect_database - 连接MySQL数据库
✅ execute_query - 执行SQL查询
✅ show_tables - 显示所有表
✅ describe_table - 显示表结构
✅ disconnect_database - 断开数据库连接

🎮 使用指南

🔌 第一步: 连接数据库

在Cline对话中输入：

请帮我连接到MySQL数据库：
- 主机: localhost
- 端口: 3306
- 用户名: root
- 密码: 你的密码
- 数据库: 你的数据库名

📊 第二步: 探索数据库

请显示这个数据库中的所有表

请显示users表的结构信息

🔍 第三步: 查询数据

请查询users表中的前10条记录

请查询年龄大于25岁的用户，按创建时间排序

请统计每个部门的用户数量

📈 第四步: 数据分析

请分析sales表中过去30天的销售趋势

请找出购买金额最高的前5名客户

🔧 高级配置

🛠️ 自定义端口

如果3100端口被占用，可以修改：

// package.json
{
  "scripts": {
    "start-gateway": "npm run build && npx supergateway --stdio \"node dist/index.js\" --port 3200"
  }
}

// Cline配置
{
  "mcpServers": {
    "mysql-database": {
      "url": "http://localhost:3200/sse",
      "type": "sse"
    }
  }
}

🔐 环境变量配置

创建 .env 文件来管理敏感信息：

# .env
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database

🚀 全局安装

# 全局安装
npm run install-global

# 然后可以在任何地方使用
mysql-mcp-server

❗ 故障排除

🔥 常见错误及解决方案

❌ npm install失败

错误信息: execution policy error 或 cannot run scripts

解决方案:

# 方案1: 修改PowerShell策略
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 方案2: 使用管理员权限运行PowerShell
# 右键点击PowerShell -> "以管理员身份运行"

# 方案3: 使用yarn代替npm
npm install -g yarn
yarn install

❌ 找不到dist/index.js

错误信息: Cannot find module 'dist/index.js'

解决方案:

# 确保构建成功
npm run build

# 检查dist目录是否存在
ls dist/

# 如果没有dist目录，重新构建
rm -rf dist/
npm run build

❌ Cline无法加载MCP服务器

错误信息: Cline显示"MCP server failed to start"

解决方案:

检查路径: 确保配置中的路径使用正斜杠 /
检查权限: 确保文件有执行权限

查看日志:

# 手动运行服务器查看错误
node dist/index.js

重启VSCode: 有时需要完全重启VSCode

❌ 数据库连接失败

错误信息: Access denied 或 Connection refused

解决方案:

✅ 确保MySQL服务正在运行
✅ 检查用户名和密码是否正确
✅ 确认数据库名称存在
✅ 检查MySQL用户权限
✅ 测试连接：
```
mysql -h localhost -u root -p
```

❌ 端口被占用

错误信息: Port 3100 is already in use

解决方案:

# 查找占用端口的进程
netstat -ano | findstr :3100

# 终止进程（替换<PID>为实际进程ID）
taskkill /PID <PID> /F

# 或者使用不同端口
npm run start-gateway -- --port 3200

🔍 调试模式

启用详细日志输出：

# 设置调试环境变量
set DEBUG=mysql-mcp:*
npm run start-gateway

# Linux/Mac用户
DEBUG=mysql-mcp:* npm run start-gateway

💡 使用技巧

🎯 最佳实践

连接管理

# 好的做法：连接前先断开之前的连接
请先断开当前数据库连接，然后连接到新的数据库

查询优化

# 大表查询时限制结果数量
请查询users表，限制100条记录并按ID排序

安全查询

# 避免查询敏感信息
请查询用户表，但不要显示密码字段

🚀 高效使用

批量操作

请依次执行以下操作：
1. 连接到数据库
2. 显示所有表
3. 查询每个表的记录数
4. 断开连接

数据分析

请分析sales表，我需要了解：
- 总销售额
- 平均订单金额
- 最畅销的产品
- 销售趋势

🔒 安全说明

🛡️ 内置安全特性

只读模式: 默认只允许SELECT查询
SQL注入防护: 自动过滤危险字符和语句
操作限制: 禁止DROP、DELETE、UPDATE、INSERT等危险操作
参数验证: 严格验证所有输入参数

🔐 安全建议

数据库用户权限

-- 创建只读用户（推荐）
CREATE USER 'mcp_user'@'localhost' IDENTIFIED BY 'strong_password';
GRANT SELECT ON your_database.* TO 'mcp_user'@'localhost';
FLUSH PRIVILEGES;

网络安全
- 仅在可信网络环境中使用
- 避免在公共网络中暴露数据库端口
密码管理
- 使用强密码
- 定期更换密码
- 考虑使用环境变量存储敏感信息

📋 常见问题

❓ Q1: MCP是什么？为什么不使用普通的API？

A: MCP（Model Context Protocol）是Anthropic开发的协议，专门为AI助手访问外部工具而设计。相比普通API，MCP提供：

标准化的工具描述格式
更好的AI集成体验
自动的权限管理
内置的安全机制

❓ Q2: 为什么选择stdio模式而不是HTTP API？

A: stdio模式的优势：

🔒 更安全：不需要开放网络端口
🚀 更简单：无需配置网络和认证
📦 更轻量：直接进程通信，性能更好
🛡️ 更隔离：每个客户端独立进程

❓ Q3: 可以连接远程MySQL数据库吗？

A: 可以！只需要在连接时指定远程主机地址：

请连接到远程数据库：
- 主机: 192.168.1.100
- 端口: 3306
- 用户名: remote_user
- 密码: remote_password
- 数据库: remote_db

❓ Q4: 支持其他数据库吗？

A: 目前只支持MySQL，但架构设计支持扩展。未来计划支持：

PostgreSQL
SQLite
SQL Server
Oracle

❓ Q5: 如何备份和恢复配置？

A:

# 备份配置
cp ~/.vscode/mcp-settings.json ~/mcp-backup.json

# 恢复配置
cp ~/mcp-backup.json ~/.vscode/mcp-settings.json

❓ Q6: 能否支持写操作？

A: 出于安全考虑，默认只支持读操作。如果需要写操作，可以：

修改 src/database.ts 中的安全限制
重新构建项目
⚠️ 注意: 这会增加数据风险，请谨慎操作

❓ Q7: 如何监控MCP服务器状态？

A:

# 检查进程
ps aux | grep "mysql-mcp"

# 检查端口（HTTP模式）
netstat -an | grep 3100

# 查看日志
tail -f ~/.vscode/logs/mcp-mysql.log

🏗️ 项目结构

my-awesome-mcp/
├── src/
│   ├── index.ts              # 🚀 MCP服务器入口点
│   └── database.ts           # 🗄️ 数据库管理器类
├── dist/                     # 📦 编译后的JavaScript文件
├── node_modules/             # 📚 依赖包
├── package.json              # ⚙️ 项目配置和脚本
├── tsconfig.json            # 🔧 TypeScript编译配置
├── README.md                # 📖 详细使用说明（本文件）
├── test-install.bat         # 🛠️ Windows一键安装脚本
└── .env.example            # 🔐 环境变量示例文件

🔄 版本更新

当前版本: v1.0.0

更新日志

✅ 修复supergateway包名错误
✅ 添加HTTP/SSE模式支持
✅ 增强安全性检查
✅ 优化错误处理
✅ 完善文档说明

更新方法

# 获取最新代码
git pull origin main

# 更新依赖
npm install

# 重新构建
npm run build

📞 技术支持

🐛 遇到问题？

查看错误日志: 在VSCode开发者控制台查看详细错误信息
检查配置: 确保所有路径和参数正确
重新安装: 删除node_modules后重新安装
查看文档: 本README包含了大部分常见问题的解决方案

📧 联系方式

GitHub Issues: 在项目仓库提交issue
讨论交流: 在GitHub Discussions中讨论
快速帮助: 在Cline中询问："如何使用MySQL MCP服务器？"

🙏 致谢

感谢以下开源项目的支持：

Model Context Protocol - Anthropic的MCP协议
mysql2 - Node.js MySQL客户端
supergateway - MCP传输层网关

📄 许可证

本项目采用 ISC 许可证 - 查看 LICENSE 文件了解详情。

💡 提示: 如果这个README帮助到了你，请给项目点个⭐Star！有问题欢迎提Issue！

🎉 现在就开始在AI对话中使用MySQL数据库吧！

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
dist		dist
node_modules		node_modules
src		src
.dockerignore		.dockerignore
Dockerfile		Dockerfile
README.md		README.md
SMITHERY_DEPLOY.md		SMITHERY_DEPLOY.md
package-lock.json		package-lock.json
package.json		package.json
smithery.yaml		smithery.yaml
test-install.bat		test-install.bat
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

MySQL MCP Server 🚀

📖 目录

🌟 功能特性

✨ 核心功能

🎯 使用场景

☁️ Smithery云部署

🚀 快速部署到Smithery

📋 部署前准备

🔧 部署步骤

🎯 使用部署的服务器

💡 云部署优势

⚙️ 配置说明

🛠️ 安装教程

📋 环境要求

🔧 一键安装脚本

📝 手动安装步骤

步骤1: 解决PowerShell权限（Windows用户）

步骤2: 安装项目依赖

步骤3: 构建项目

⚙️ 配置方法

🎯 配置方式选择

📌 方法1: stdio模式配置（推荐新手）

步骤1: 打开Cline配置

步骤2: 添加配置

步骤3: 重启VSCode

🌐 方法2: HTTP/SSE模式配置（推荐高级用户）

步骤1: 启动Gateway服务

步骤2: 配置Cline

步骤3: 重启VSCode

🔄 验证配置是否成功

🎮 使用指南

🔌 第一步: 连接数据库

📊 第二步: 探索数据库

🔍 第三步: 查询数据

📈 第四步: 数据分析

🔧 高级配置

🛠️ 自定义端口

🔐 环境变量配置

🚀 全局安装

❗ 故障排除

🔥 常见错误及解决方案

❌ npm install失败

❌ 找不到dist/index.js

❌ Cline无法加载MCP服务器

❌ 数据库连接失败

❌ 端口被占用

🔍 调试模式

💡 使用技巧

🎯 最佳实践

🚀 高效使用

🔒 安全说明

🛡️ 内置安全特性

🔐 安全建议

📋 常见问题

❓ Q1: MCP是什么？为什么不使用普通的API？

❓ Q2: 为什么选择stdio模式而不是HTTP API？

❓ Q3: 可以连接远程MySQL数据库吗？

❓ Q4: 支持其他数据库吗？

❓ Q5: 如何备份和恢复配置？

❓ Q6: 能否支持写操作？

❓ Q7: 如何监控MCP服务器状态？

🏗️ 项目结构

🔄 版本更新

当前版本: v1.0.0

更新日志

更新方法

📞 技术支持

🐛 遇到问题？

📧 联系方式

🙏 致谢

📄 许可证

About

Resources

Uh oh!

Stars

Watchers

Packages