mysql-mcp-server

GuangYiDing/mysql-mcp-server

3.2

If you are the rightful owner of mysql-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The MySQL MCP Server is a Model Context Protocol server designed for interacting with MySQL databases, providing a range of tools for database management and query execution.

Tools
5
Resources
0
Prompts
0

🐬 MySQL MCP Server

简体中文 |

npm version CI Publish npm downloads License: MIT

一个用于 MySQL 数据库操作的 Model Context Protocol (MCP) 服务器。

✨ 功能特性

这个 MCP 服务器提供了以下工具来与 MySQL 数据库交互：

🔌 连接管理 (支持多连接)

  • connect - 建立命名数据库连接，支持同时管理多个连接
  • list_connections - 列出所有已建立的连接及其状态
  • switch_connection - 切换当前活动连接
  • disconnect - 断开指定连接

📊 查询操作

  • query - 执行 SQL 查询语句（SELECT）
  • execute - 执行 SQL 修改语句（INSERT, UPDATE, DELETE 等）
  • explain - 查看 SQL 查询语句的执行计划，用于性能分析和优化

🗄️ 数据库管理

  • list_databases - 列出所有数据库
  • list_tables - 列出指定数据库中的所有表
  • describe_table - 查看表结构

📦 安装

通过 npm 安装（推荐）

npm install -g @nolimit35/mysql-mcp-server

从源码构建

git clone https://github.com/GuangYiDing/mysql-mcp-server.git
cd mysql-mcp-server
npm install
npm run build

🚀 使用方法

在 Claude Code 中配置

提供多种配置方式：

方式一：使用 npx（推荐，无需全局安装）

编辑配置文件 ~/.claude/settings.json，添加以下配置：

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@nolimit35/mysql-mcp-server"
      ],
      "env": {
        "MYSQL_DATASOURCES": "|dev|username:pass@192.168.xx.xx:3306/xxx;",
        "MYSQL_DANGER_MODE": "false",
        "LOG_LEVEL": "INFO",
        "LOG_COLORS": "true"
      }
    }
  }
}
方式二：使用命令行配置

在终端执行以下命令：

claude mcp add --transport stdio mysql-mcp --scope user \
  --env MYSQL_DATASOURCES="|dev|username:pass@192.168.xx.xx:3306/xxx;" \
  --env MYSQL_DANGER_MODE=false \
  -- npx -y @nolimit35/mysql-mcp-server
⚙️ 配置说明
  • command: 执行命令（npx）
  • args: 命令参数 ["-y", "@nolimit35/mysql-mcp-server"]
  • env: 环境变量配置
    • MYSQL_DATASOURCES: 数据源配置，格式为 |连接名|连接字符串;，可配置多个数据源用分号分隔
    • MYSQL_DANGER_MODE: 危险模式开关，设置为 "true" 允许执行修改操作（INSERT/UPDATE/DELETE 等）
    • LOG_LEVEL: 日志级别，可选值：DEBUG、INFO（默认）、WARN、ERROR、OFF
    • LOG_COLORS: 是否启用彩色日志输出，默认为 "true"
📝 数据源配置格式
|连接名1|username:password@host:port/database;|连接名2|username:password@host:port/database;

示例：

|dev|root:pass123@localhost:3306/dev_db;|prod|app_user:pass456@192.168.1.100:3306/prod_db;

配置完成后，重启 Claude Code 使配置生效。

💡 使用示例

📚 基础操作

  1. 连接数据库 (从预配置数据源):

    连接到名为 dev 的数据源

    ⚠️ 注意: connect 工具只能连接到通过环境变量 MYSQL_DATASOURCES 预配置的数据源。 如需添加新数据源，请在配置文件中修改 MYSQL_DATASOURCES 环境变量并重启 Claude Code。

  2. 查询数据:

    查询test数据库中users表的所有数据

  3. 列出数据库:

    列出所有可用的数据库

  4. 查看表结构:

    查看users表的结构

  5. 执行插入操作 (需要危险模式):

    向users表插入一条记录,name为'John',age为30,并启用危险模式

  6. 执行更新操作 (需要危险模式):

    更新users表中id为1的记录,设置age为31,启用危险模式

  7. 查看执行计划:

    查看这条SQL语句的执行计划: SELECT * FROM users WHERE age > 25
🔄 多连接管理示例

场景1: 跨环境数据对比

1. 连接到开发环境数据库,名称为dev
2. 连接到生产环境数据库,名称为prod
3. 列出所有连接
4. 查询dev环境的users表
5. 切换到prod连接
6. 查询prod环境的users表

场景2: 数据迁移

1. 连接源数据库,命名为source
2. 连接目标数据库,命名为target
3. 从source数据库查询要迁移的数据
4. 显式指定使用target连接执行插入操作(需要危险模式)
5. 验证target数据库的数据

场景3: 多项目管理

1. 连接project1数据库
2. 连接project2数据库
3. 连接project3数据库
4. 使用list_connections查看所有连接状态
5. 使用switch_connection快速切换项目
6. 完成后使用disconnect关闭不需要的连接

🛠️ 工具详情

🔌 连接管理工具

connect 🔗

连接到预配置的 MySQL 数据源

⚠️ 重要: 此工具只能连接到通过环境变量 MYSQL_DATASOURCES 预配置的数据源。服务器启动时会自动初始化所有预配置的连接。

参数:

  • connectionName (string, 必需) - 要连接的数据源名称（必须是在环境变量 MYSQL_DATASOURCES 中预配置的名称）

功能说明:

  • 连接到预配置数据源并设为当前活动连接
  • 验证连接是否可用
  • 自动处理连接切换

配置数据源: 在配置文件的 env 中设置 MYSQL_DATASOURCES：

{
  "env": {
    "MYSQL_DATASOURCES": "|dev|root:password@localhost:3306/mydb;|prod|user:pass@prod.example.com/database"
  }
}

数据源格式: |连接名|username:password@host:port/database

  • port 和 database 是可选的，默认端口为 3306
  • 多个数据源用分号(;)分隔
  • 示例: |local|root:pass@localhost
  • 示例: |prod|user:pass@192.168.1.100:3306/mydb

注意事项:

  • 服务器启动时会自动连接所有预配置的数据源
  • 第一个成功连接的数据源会自动设为当前活动连接
  • 如需添加新数据源，需修改配置文件并重启服务
  • 连接失败时会提供详细的配置指导
list_connections 📋

列出所有已建立的数据库连接及其状态

参数: 无

返回示例:

数据库连接列表 (共 3 个):

📌 dev ← 当前活动
   地址: localhost:3306
   用户: root
   数据库: dev_db

📌 test
   地址: localhost:3306
   用户: root
   数据库: test_db

📌 prod
   地址: prod-server:3306
   用户: app_user
   数据库: prod_db
switch_connection 🔀

切换当前活动的数据库连接

参数:

  • connectionName (string, 必需) - 要切换到的连接名称

使用场景: 在多个数据库之间快速切换，后续操作会使用切换后的连接

disconnect ❌

断开指定的数据库连接

参数:

  • connectionName (string, 必需) - 要断开的连接名称

注意:

  • 如果断开的是当前活动连接,会自动切换到其他可用连接
  • 如果没有其他连接,需要重新使用 connect 建立连接

📊 数据库操作工具

query 🔍

执行 SQL 查询语句（SELECT）

参数:

  • sql (string, 必需) - 要执行的 SQL 查询语句
  • database (string, 可选) - 切换到指定数据库
  • connectionName (string, 可选) - 指定使用的连接，默认使用当前活动连接
execute ⚡

执行 SQL 修改语句（INSERT, UPDATE, DELETE 等）

⚠️ 危险模式保护: 为了防止意外的数据修改或删除,执行危险操作时必须显式启用 dangerousMode 参数。

参数:

  • sql (string, 必需) - 要执行的SQL语句
  • dangerousMode (boolean, 默认false) - 危险模式开关,执行以下操作时必须设置为 true:
    • INSERT - 插入数据
    • UPDATE - 更新数据
    • DELETE - 删除数据
    • DROP - 删除表或数据库
    • ALTER - 修改表结构
    • TRUNCATE - 清空表
    • CREATE - 创建表或数据库
    • RENAME - 重命名表
    • REPLACE - 替换数据
  • database (string, 可选) - 切换到指定数据库
  • connectionName (string, 可选) - 指定使用的连接,默认使用当前活动连接

示例:

// ❌ 这会被拒绝 (未启用危险模式)
{"sql": "DELETE FROM users WHERE id=1"}

// ✅ 这会成功执行 (已启用危险模式)
{"sql": "DELETE FROM users WHERE id=1", "dangerousMode": true}

// ✅ 安全操作不需要危险模式
{"sql": "SHOW TABLES"}
list_databases 🗄️

列出所有数据库

参数:

  • connectionName (string, 可选) - 指定使用的连接，默认使用当前活动连接
list_tables 📑

列出指定数据库中的所有表

参数:

  • database (string, 可选) - 数据库名称（如果已连接到数据库）
  • connectionName (string, 可选) - 指定使用的连接，默认使用当前活动连接
describe_table 📋

查看表结构

参数:

  • table (string, 必需) - 表名称
  • database (string, 可选) - 数据库名称
  • connectionName (string, 可选) - 指定使用的连接，默认使用当前活动连接
explain 📈

查看 SQL 查询语句的执行计划，用于分析和优化查询性能

参数:

  • sql (string, 必需) - 要分析的SQL查询语句
  • format (string, 可选, 默认"default") - 执行计划输出格式
    • default - 传统表格格式
    • json - JSON格式,更适合程序解析
    • tree - 树形格式,更直观(需要MySQL 8.0.16+)
    • analyze - 实际执行查询并显示详细统计信息(需要MySQL 8.0.18+,会真实执行查询)
  • database (string, 可选) - 切换到指定数据库
  • connectionName (string, 可选) - 指定使用的连接,默认使用当前活动连接

示例:

-- 默认格式
EXPLAIN SELECT * FROM users WHERE age > 25

-- JSON格式
EXPLAIN FORMAT=JSON SELECT * FROM users WHERE age > 25

-- 树形格式(MySQL 8.0.16+)
EXPLAIN FORMAT=TREE SELECT * FROM users WHERE age > 25

-- 分析格式(MySQL 8.0.18+,实际执行查询)
EXPLAIN ANALYZE SELECT * FROM users WHERE age > 25

注意:

  • analyze 格式会实际执行查询语句,请谨慎在生产环境使用
  • tree 和 analyze 格式需要较新版本的MySQL支持

📝 日志配置

本服务器提供了灵活的日志系统，支持不同的日志级别和输出格式。

📊 日志级别

通过环境变量 LOG_LEVEL 配置日志级别，可选值：

级别说明用途
DEBUG调试信息开发环境，输出详细的调试信息
INFO一般信息（默认）生产环境，输出正常的运行信息
WARN警告信息输出需要关注但不影响运行的警告
ERROR错误信息仅输出错误信息
OFF关闭日志完全关闭日志输出

日志格式

日志输出格式为：

<时间戳> [级别] <消息> [数据]

示例：

2025-01-15T10:30:45.123Z [INFO] MySQL连接池已初始化: [dev] localhost:3306
2025-01-15T10:30:45.456Z [ERROR] 数据源 [prod] 连接失败: Connection timeout

🎨 彩色输出

通过环境变量 LOG_COLORS 控制是否启用彩色日志输出（默认启用）：

  • LOG_COLORS=true - 启用彩色输出（推荐用于终端查看）
  • LOG_COLORS=false - 禁用彩色输出（推荐用于日志文件）

⚙️ 配置示例

开发环境配置（详细日志）：

{
  "env": {
    "LOG_LEVEL": "DEBUG",
    "LOG_COLORS": "true"
  }
}

生产环境配置（标准日志）：

{
  "env": {
    "LOG_LEVEL": "INFO",
    "LOG_COLORS": "false"
  }
}

静默模式（仅错误）：

{
  "env": {
    "LOG_LEVEL": "ERROR",
    "LOG_COLORS": "false"
  }
}

🔒 安全注意事项

⚠️ 重要：

🛡️ 连接安全

  • 不要在生产环境中存储明文密码
  • 建议使用环境变量来存储敏感信息
  • 限制数据库用户权限,只授予必要的操作权限
  • 使用防火墙规则限制数据库访问

⚠️ 操作安全 - 危险模式保护

为了防止意外的数据修改或删除，本服务器实现了危险模式保护机制：

  • 默认安全: 所有危险操作(INSERT/UPDATE/DELETE/DROP/ALTER等)默认被拒绝
  • 显式确认: 必须显式设置 dangerousMode=true 才能执行危险操作
  • 智能检测: 自动检测SQL语句类型,识别潜在危险操作
  • 操作审计: 建议在生产环境记录所有危险操作的日志

受保护的操作类型:

  • 数据修改: INSERT, UPDATE, DELETE, REPLACE
  • 结构修改: DROP, ALTER, TRUNCATE, RENAME
  • 对象创建: CREATE

最佳实践:

  1. 在执行危险操作前,先使用 query 工具验证目标数据
  2. 对于批量操作,建议先在测试环境验证
  3. 生产环境中谨慎使用 DROP 和 TRUNCATE 操作
  4. 始终使用 WHERE 子句限制 UPDATE 和 DELETE 的影响范围

🛠️ 开发

# 克隆项目
git clone https://github.com/GuangYiDing/mysql-mcp-server.git
cd mysql-mcp-server

# 安装依赖
npm install

# 构建项目
npm run build

# 开发模式（监听文件变化）
npm run dev

🔧 技术栈

  • TypeScript - 类型安全的 JavaScript
  • @modelcontextprotocol/sdk - MCP SDK
  • mysql2 - MySQL 数据库驱动
  • zod - 参数验证

📄 许可证

MIT

🤝 贡献

欢迎提交问题和拉取请求！

🔗 相关资源