🐬 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 使配置生效。

💡 使用示例

📚 基础操作

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

🤝 贡献

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

🔗 相关资源

• Model Context Protocol 文档
• MySQL 文档
• Claude Code
• npm 包地址
• GitHub 仓库