🐬 MySQL MCP Server

简体中文 | English

一个用于 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 使配置生效。

💡 使用示例

📚 基础操作

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

查询数据:

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

列出数据库:
```
列出所有可用的数据库
```
查看表结构:
```
查看users表的结构
```

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

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

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

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

查看执行计划:

查看这条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

最佳实践:

在执行危险操作前,先使用 query 工具验证目标数据
对于批量操作,建议先在测试环境验证
生产环境中谨慎使用 DROP 和 TRUNCATE 操作
始终使用 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

🤝 贡献

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

🔗 相关资源