❤
npm
Sign UpSign In

@xingyuchen/mysql-mcp-server

3.0.0 • Public • Published

MySQL MCP Server 3.0 🚀

一个功能强大且易用的MySQL数据库MCP（Model Context Protocol）服务器，让你的AI助手可以安全地进行完整的数据库操作，支持多数据库连接管理、增删改查、事务管理和智能回滚功能。

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

📖 目录

🌟 功能特性

✨ 核心功能

  • 📦 NPM包支持: 一键安装 npm install -g @xingyuchen/mysql-mcp-server，即装即用
  • 🔗 多数据库连接: 同时管理多个MySQL数据库连接，无需频繁切换
  • 🎯 智能连接管理: 支持连接标识、活跃连接切换和连接状态监控
  • 🔄 完整CRUD操作: 支持INSERT、UPDATE、DELETE、SELECT等所有SQL操作
  • 🛡️ 自动事务管理: 修改操作自动开启事务，支持智能回滚
  • 📊 增强表查看: 显示表结构概览、行数统计和样本数据
  • 📝 智能日志系统: 详细记录所有操作，支持错误追踪和性能分析
  • 🔙 历史回滚功能: 查看操作历史，选择性回滚到任意步骤
  • 🚀 双模式部署: 支持stdio模式和HTTP/SSE模式

🎯 使用场景

  • ✅ 完整的数据库CRUD操作（增删改查）
  • ✅ 数据库结构分析和优化建议
  • ✅ 批量数据处理和迁移
  • ✅ 事务安全的数据修改
  • ✅ 数据备份前的安全测试
  • ✅ 复杂查询的构建和调试

🆕 3.0版本新特性

  • 🔗 多数据库连接: 同时管理多个MySQL数据库，支持连接池
  • 🎯 连接管理: 新增连接列表、切换活跃连接、移除连接等管理工具
  • 📋 灵活切换: 所有操作支持指定connection_id参数选择目标数据库
  • 🚀 向后兼容: 保持现有API不变，新功能通过可选参数提供
  • 📊 连接监控: 显示连接状态、连接时间和数据库信息

📜 历史版本特性

  • 2.0版本: 工具简化、增强展示、完整回滚、实时监控、安全升级
  • 1.0版本: 基础CRUD操作、事务管理、日志系统

🔧 工具概览

核心工具 (14个)

工具名称 功能描述 使用场景
connect_database 连接MySQL数据库 建立数据库连接（支持连接ID）
execute_query 万能SQL执行工具 执行任何SQL操作（CRUD、DDL等）
show_tables 显示所有表及结构概览 快速了解数据库整体结构
describe_table 显示表详细结构和样本数据 深入了解特定表的结构和内容
begin_transaction 开始事务 手动控制事务开始
commit_transaction 提交事务 确认所有修改
rollback_transaction 回滚事务 撤销所有未提交修改
show_transaction_history 显示事务历史 查看所有操作记录
rollback_to_step 回滚到指定步骤 选择性撤销操作
full_rollback 完全回滚 撤销所有事务内操作
disconnect_database 断开数据库连接 安全关闭连接
list_connections 列出所有数据库连接 查看连接状态和信息
switch_active_connection 切换活跃连接 在多个数据库间切换
remove_connection 移除指定连接 清理不需要的连接

🎯 主要改进

1. 工具简化

旧版本: 15个工具 (insert_data, update_data, delete_data, select_data, create_table, drop_table, get_table_info...)
新版本: 11个工具 (保留万能的execute_query，删除重复功能)

2. 增强展示

show_tables 输出示例:
📋 数据库概览
📊 总共找到 3 个表:

🗂️ **users**
   📊 行数: 1250
   🏗️ 列: id(int), name(varchar), email(varchar), created_at(datetime)

🗂️ **orders**
   📊 行数: 3420
   🏗️ 列: id(int), user_id(int), amount(decimal), status(enum), order_date(datetime)

3. 样本数据展示

describe_table 输出示例:
🔍 表 "users" 的详细信息

📊 基本信息:
   总行数: 1250
   总列数: 4

🏗️ 表结构:
字段名               | 类型            | 可为空   | 键      | 默认值     | 额外信息
================================================================================
id                   | int(11)         | NO       | PRI     | NULL       | auto_increment
name                 | varchar(100)    | NO       |         | NULL       |
email                | varchar(255)    | YES      | UNI     | NULL       |
created_at           | datetime        | YES      |         | NULL       |

📄 样本数据 (前5行):
[
  {
    "id": 1,
    "name": "张三",
    "email": "zhangsan@example.com",
    "created_at": "2024-01-15T10:30:00.000Z"
  },
  ...
]

4. 智能事务管理

自动功能:
- INSERT/UPDATE/DELETE操作自动开启事务
- 自动生成精确的回滚查询
- 记录每个操作的详细信息
- 支持选择性回滚到任意步骤

回滚查询示例:
INSERT → DELETE FROM table WHERE id = ?
UPDATE → UPDATE table SET col1=?, col2=? WHERE condition
DELETE → INSERT INTO table (col1, col2) VALUES (?, ?)

☁️ Smithery云部署

🚀 快速部署到Smithery

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

🔧 部署步骤

  1. Fork项目到您的GitHub

    https://github.com/guangxiangdebizi/MySQL_MCP

  2. 登录Smithery平台

  3. 连接GitHub仓库

    • 点击 "Deploy Server"
    • 选择您Fork的 MySQL_MCP 仓库
    • 确认部署配置

  4. 使用部署的服务器

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

🛠️ 安装教程

📋 环境要求

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

🚀 方法1: NPM安装（推荐）

# 全局安装
npm install -g @xingyuchen/mysql-mcp-server

# 验证安装
guangxiang-mysql-mcp --help

🔧 方法2: 源码安装

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

# 2. 安装依赖
npm install

# 3. 构建项目
npm run build

# 4. 测试安装
npm test

⚙️ 配置方法

📌 方法1: NPM包配置（推荐）

使用npm全局安装后，在Cline设置中添加：

{
  "mcpServers": {
    "mysql-database": {
      "command": "guangxiang-mysql-mcp",
      "env": {}
    }
  }
}

📌 方法2: 本地项目配置

如果使用npx或本地安装：

{
  "mcpServers": {
    "mysql-database": {
      "command": "npx",
      "args": ["@xingyuchen/mysql-mcp-server"],
      "env": {}
    }
  }
}

📌 方法3: 源码配置

从源码安装后，在Cline设置中添加：

{
  "mcpServers": {
    "mysql-database": {
      "command": "node",
      "args": ["C:/path/to/my-awesome-mcp/dist/index.js"],
      "env": {}
    }
  }
}

📌 方法4: HTTP/SSE模式配置

{
  "mcpServers": {
    "mysql-database": {
      "url": "http://localhost:3101/sse",
      "type": "sse"
    }
  }
}

启动服务器：

npm run start-gateway

🎮 使用指南

🚀 基础连接

单数据库连接（3.0保持兼容）

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

🆕 多数据库连接（3.0新功能）

# 连接第一个数据库（自动成为活跃连接）
请连接到生产数据库：
- 主机: prod.mysql.com
- 数据库: production_db
- 连接ID: prod

# 连接第二个数据库
请连接到测试数据库：
- 主机: test.mysql.com  
- 数据库: test_db
- 连接ID: test

# 查看所有连接
请列出所有数据库连接

# 切换活跃连接
请切换到test连接

# 指定连接执行操作
请在prod连接上查询用户表

📊 查看数据库结构

# 查看所有表概览
请显示数据库中的所有表

# 查看特定表详情
请描述users表的结构

🔄 执行CRUD操作

-- 查询数据
SELECT * FROM users WHERE age > 25 LIMIT 10

-- 插入数据  
INSERT INTO users (name, email, age) VALUES ('张三', 'zhang@example.com', 28)

-- 更新数据
UPDATE users SET age = 29 WHERE email = 'zhang@example.com'

-- 删除数据
DELETE FROM users WHERE id = 123

🛡️ 事务安全操作

# 查看事务历史
请显示当前事务的操作历史

# 回滚到特定步骤
请回滚到第3步操作之前

# 完全回滚
请完全回滚所有未提交的操作

# 提交事务
请提交当前事务

🔄 事务管理

自动事务管理

  • 自动开启: INSERT/UPDATE/DELETE操作自动开启事务
  • 智能记录: 记录每个操作的详细信息和回滚查询
  • 精确回滚: 支持回滚到任意操作步骤

事务历史示例

📋 事务历史记录

🔹 步骤 1 (2024-01-15 10:30:15)
   类型: INSERT | 表: users | 影响行数: 1
   描述: 执行 INSERT 操作，影响 1 行
   SQL: INSERT INTO users (name, email) VALUES (?, ?)
   回滚: DELETE FROM users WHERE id = ?

🔹 步骤 2 (2024-01-15 10:31:22)  
   类型: UPDATE | 表: users | 影响行数: 1
   描述: 执行 UPDATE 操作，影响 1 行
   SQL: UPDATE users SET age = ? WHERE id = ?
   回滚: UPDATE users SET age = ? WHERE id = ?

💡 使用 rollback_to_step 可以回滚到任意步骤

📊 日志系统

日志文件类型

日志文件 内容 用途
combined-*.log 所有日志信息 全面的操作记录
error-*.log 错误信息 问题诊断
database-*.log 数据库操作 SQL执行追踪
exceptions-*.log 异常信息 系统异常分析

查看日志

# 查看实时日志
npm run logs:tail

# 查看错误日志
npm run logs:errors

# 分析数据库操作
npm run logs:db-analysis

💡 使用技巧

🎯 最佳实践

  1. 数据探索

    先用show_tables了解整体结构
再用describe_table查看具体表
最后用execute_query进行操作

  2. 安全修改

    重要操作前先SELECT确认数据
使用事务保护批量修改
及时查看事务历史

  3. 性能优化

    使用LIMIT限制结果集大小
添加WHERE条件过滤数据
查看日志分析慢查询

🚀 高级用法

-- 复杂查询
SELECT u.name, COUNT(o.id) as order_count, SUM(o.amount) as total_amount
FROM users u 
LEFT JOIN orders o ON u.id = o.user_id 
WHERE u.created_at >= '2024-01-01'
GROUP BY u.id, u.name
HAVING total_amount > 1000
ORDER BY total_amount DESC
LIMIT 20

-- 批量操作
INSERT INTO products (name, price, category_id) VALUES 
('产品A', 99.99, 1),
('产品B', 149.99, 2),
('产品C', 199.99, 1)

-- 条件更新
UPDATE inventory 
SET stock = stock - 1 
WHERE product_id = 123 AND stock > 0

🔒 安全说明

⚠️ 重要提醒

  • 完整权限: 2.0版本支持完整CRUD操作，请谨慎使用
  • 事务保护: 所有修改操作都有事务保护和回滚功能
  • 日志记录: 所有操作都会被详细记录
  • 用户权限: 建议创建专门的数据库用户，限制必要权限

🛡️ 安全建议

  1. 数据库用户

    CREATE USER 'mcp_user'@'localhost' IDENTIFIED BY 'strong_password';
GRANT SELECT, INSERT, UPDATE, DELETE ON your_database.* TO 'mcp_user'@'localhost';

  2. 备份策略

    重要操作前先备份数据
定期检查事务历史
保留操作日志用于审计

❗ 故障排除

常见问题

  1. 连接失败

    检查MySQL服务是否运行
确认连接参数正确
查看error日志获取详细信息

  2. 权限错误

    确认数据库用户权限
检查表的访问权限
查看MySQL错误日志

  3. 事务问题

    使用show_transaction_history查看状态
必要时使用full_rollback重置
检查database日志分析问题

📦 发布相关

🚀 NPM包发布

本项目已配置为标准的NPM包，支持一键发布到npm仓库。

📚 发布文档

🎯 快速发布

# 1. 登录NPM（首次发布需要）
npm login

# 2. 发布包
npm publish

# 3. 验证发布
npm view @xingyuchen/mysql-mcp-server

👥 用户安装

发布后，用户可以通过以下方式安装：

# 全局安装
npm install -g @xingyuchen/mysql-mcp-server

# 在Cline中配置
{
  "mcpServers": {
    "mysql-database": {
      "command": "guangxiang-mysql-mcp",
      "env": {}
    }
  }
}

📞 支持与反馈

⭐ 如果这个项目对你有帮助，请给个Star支持一下！

Readme

Keywords

Package Sidebar

Install

npm i @xingyuchen/mysql-mcp-server

Repository

github.com/guangxiangdebizi/MySQL_MCP

Homepage

github.com/guangxiangdebizi/MySQL_MCP#readme

Weekly Downloads

4

Version

3.0.0

License

MIT

Unpacked Size

106 kB

Total Files

11

Last publish

Collaborators

  • xingyuchen
Try on RunKit
Report malware