MySQL MCP Server

# 🐬 MySQL MCP Server **简体中文** | [English](README.en.md) [](https://www.npmjs.com/package/@nolimit35/mysql-mcp-server) [](https://github.com/GuangYiDing/mysql-mcp-server/actions/workflows/ci.yml) [](https://github.com/GuangYiDing/mysql-mcp-server/actions/workflows/publish.yml) [](https://www.npmjs.com/package/@nolimit35/mysql-mcp-server) [](https://opensource.org/licenses/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 安装（推荐） ```bash npm install -g @nolimit35/mysql-mcp-server ``` ### 从源码构建 ```bash 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`，添加以下配置： ```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" } } } } ``` #### 方式二：使用命令行配置 在终端执行以下命令： ```bash 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`： ```json { "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, 可选) - 指定使用的连接,默认使用当前活动连接 **示例**: ```json // ❌ 这会被拒绝 (未启用危险模式) {"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, 可选) - 指定使用的连接,默认使用当前活动连接 **示例**: ```sql -- 默认格式 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` - 禁用彩色输出（推荐用于日志文件） ### ⚙️ 配置示例 **开发环境配置**（详细日志）： ```json { "env": { "LOG_LEVEL": "DEBUG", "LOG_COLORS": "true" } } ``` **生产环境配置**（标准日志）： ```json { "env": { "LOG_LEVEL": "INFO", "LOG_COLORS": "false" } } ``` **静默模式**（仅错误）： ```json { "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` 的影响范围 ## 🛠️ 开发 ```bash # 克隆项目 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 文档](https://modelcontextprotocol.io) - [MySQL 文档](https://dev.mysql.com/doc/) - [Claude Code](https://claude.ai/download) - [npm 包地址](https://www.npmjs.com/package/@nolimit35/mysql-mcp-server) - [GitHub 仓库](https://github.com/GuangYiDing/mysql-mcp-server)