mcp-mysql-caidingnu

基于 Model Context Protocol (MCP) 的 MySQL 数据库操作服务，支持连接管理、CRUD（SELECT/INSERT/UPDATE/DELETE）、DDL（CREATE/ALTER/DROP/TRUNCATE）操作和表结构探查。

环境要求

• Node.js >= 20

使用方式

方式一：npx 直接运行（推荐，无需安装）

在 MCP 客户端配置中直接使用 npx，自动从 npm 拉取并执行：

{
  "mcpServers": {
    "mcp-mysql-caidingnu": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-mysql-caidingnu"],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your-password",
        "MYSQL_DATABASE": "your-database"
      }
    }
  }
}

MYSQL_DDL 是可选配置，默认无需添加。需要跳过 DROP/TRUNCATE 二次确认时，在 env 中增加：

{
  "MYSQL_DATABASE": "your-database",
  "MYSQL_DDL": "true"
}

启用后可省略 confirmDestructive；如果仍显式传入 "N"/"n"，操作始终取消。修改 MCP 配置后需要重启 MCP 服务才会生效。

方式二：全局安装

npm install -g mcp-mysql-caidingnu

安装后二进制命令 mcp-mysql-caidingnu 添加到系统 PATH：

{
  "mcpServers": {
    "mcp-mysql-caidingnu": {
      "type": "stdio",
      "command": "mcp-mysql-caidingnu",
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your-password",
        "MYSQL_DATABASE": "your-database"
      }
    }
  }
}

各工具配置指南

以上 JSON 配置兼容所有支持 MCP 的客户端：

| 工具 | 配置文件位置 | |------|-------------| | CodeBuddy | ~/.codebuddy/mcp.json | | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows) | | Cursor | .cursor/mcp.json（项目根目录）或 ~/.cursor/mcp.json | | VS Code / Cline | 通过 MCP 设置面板添加 | | Zed | ~/.config/zed/mcp.json 或 ~/.zed/mcp.json |

环境变量（自动连接）

若设置了 MYSQL_HOST，启动时会自动建立初始连接，无需手动调用 mysql_connect。自动连接的 ID 取 MYSQL_DATABASE 的值，若未设置则为 "default"。

| 变量 | 必填 | 默认值 | 说明 | |------|------|--------|------| | MYSQL_HOST | 否 | — | MySQL 主机地址。不设置则通过 mysql_connect 工具手动连接 | | MYSQL_PORT | 否 | 3306 | MySQL 端口 | | MYSQL_USER | 否 | root | 用户名 | | MYSQL_PASSWORD | 否 | 空字符串 | 密码 | | MYSQL_DATABASE | 否 | — | 默认数据库 | | MYSQL_DDL | 否 | 未配置（安全模式） | 仅值为 true 时跳过 DROP/TRUNCATE 的 Y/N 二次确认；忽略大小写和首尾空格。不配置或其他值均保持确认流程，配置变更后需重启 MCP 服务 |

可用工具

mysql_connect — 建立 MySQL 连接

动态建立 MySQL 连接池，凭据仅保存在当前 MCP 进程内存中。

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | host | string | 是 | — | MySQL 主机地址 | | port | number | 否 | 3306 | 端口，范围 1 ~ 65535 | | user | string | 是 | — | 用户名 | | password | string | 否 | "" | 密码 | | database | string | 否 | — | 默认数据库 | | label | string | 否 | {user}@{host}:{port} | 自定义连接标签 | | ssl | boolean | 否 | false | 是否启用 MySQL TLS 加密连接 | | connectTimeoutMs | number | 否 | 10000 | 连接超时毫秒数，范围 1000 ~ 120000 |

返回 { connectionId, host, port, user, database }。

mysql_list_connections — 列出所有连接

列出当前 MCP 会话中所有活跃连接，密码不会出现在返回结果中。

无参数。

返回连接列表，每项包含 connectionId、label、host、port、user、database、createdAt。

mysql_disconnect — 关闭连接

关闭指定连接池并从内存中移除。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | connectionId | string | 是 | mysql_connect 返回的连接 ID |

返回 { disconnected: true, connectionId }。

mysql_query — 执行只读 SQL

仅允许执行 SELECT、SHOW、DESCRIBE、DESC、EXPLAIN 语句，其他 SQL 类型会被拒绝；SELECT INTO OUTFILE / DUMPFILE 也会被拒绝。支持 ? 参数化占位符。

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | connectionId | string | 是 | — | 连接 ID | | sql | string | 是 | — | 只读 SQL 语句 | | parameters | array | 否 | [] | ? 占位符参数，元素类型为 string / number / boolean / null |

返回 { rowCount, columns: string[], rows: object[] }。

mysql_execute — 通用执行（兜底）

通用执行入口：仅执行单条 INSERT、UPDATE、DELETE、CREATE TABLE、ALTER TABLE、DROP TABLE 或 TRUNCATE TABLE。不配置 MYSQL_DDL=true 时，DROP/TRUNCATE 必须在征得用户明确同意后将 confirmDestructive 设为 "Y"/"y"；配置后可省略该参数。显式传 "N"/"n" 始终取消。建议优先使用语义化专用工具。支持 ? 参数化占位符。

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | connectionId | string | 是 | — | 连接 ID | | sql | string | 是 | — | 写入或 DDL 语句 | | parameters | array | 否 | [] | ? 占位符参数 | | confirmDestructive | string | 否 | — | DROP/TRUNCATE 默认需在用户同意后传 Y/y；MYSQL_DDL=true 时可省略；N/n 始终取消。非破坏性语句无需传入 |

返回 { affectedRows, changedRows, insertId, warningStatus }。

mysql_insert — 插入数据（INSERT，DML）

执行 INSERT 语句，向表中插入一行或多行数据。支持 ? 参数化占位符。

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | connectionId | string | 是 | — | 连接 ID | | sql | string | 是 | — | INSERT 语句 | | parameters | array | 否 | [] | ? 占位符参数 |

返回 { affectedRows, insertId, warningStatus }。

mysql_update — 更新数据（UPDATE，DML）

执行 UPDATE 语句，更新表中符合条件的数据。支持 ? 参数化占位符。

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | connectionId | string | 是 | — | 连接 ID | | sql | string | 是 | — | UPDATE 语句 | | parameters | array | 否 | [] | ? 占位符参数 |

返回 { affectedRows, changedRows, warningStatus }。

mysql_delete — 删除数据（DELETE，DML）

执行 DELETE 语句，删除表中符合条件的数据。支持 ? 参数化占位符。

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | connectionId | string | 是 | — | 连接 ID | | sql | string | 是 | — | DELETE 语句 | | parameters | array | 否 | [] | ? 占位符参数 |

返回 { affectedRows, changedRows, warningStatus }。

mysql_create_table — 建表（CREATE TABLE，DDL）

执行 CREATE TABLE 语句，创建新表。支持 ? 参数化占位符。

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | connectionId | string | 是 | — | 连接 ID | | sql | string | 是 | — | CREATE TABLE 语句 | | parameters | array | 否 | [] | ? 占位符参数 |

返回 { affectedRows, warningStatus }。

mysql_alter_table — 改表结构（ALTER TABLE，DDL）

执行 ALTER TABLE 语句，修改表结构（增删列、加索引等）。支持 ? 参数化占位符。

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | connectionId | string | 是 | — | 连接 ID | | sql | string | 是 | — | ALTER TABLE 语句 | | parameters | array | 否 | [] | ? 占位符参数 |

返回 { affectedRows, warningStatus }。

mysql_drop_table — 删表（DROP TABLE，DDL）

执行 DROP TABLE 语句，删除整张表。属于破坏性操作：默认必须在用户同意后传 confirmDestructive: "Y"/"y"；配置 MYSQL_DDL=true 后可省略。显式传 "N"/"n" 始终取消。支持 ? 参数化占位符。

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | connectionId | string | 是 | — | 连接 ID | | sql | string | 是 | — | DROP TABLE 语句 | | parameters | array | 否 | [] | ? 占位符参数 | | confirmDestructive | string | 否 | — | 默认需在用户同意后传 Y/y；MYSQL_DDL=true 时可省略；N/n 始终取消 |

返回 { affectedRows, warningStatus }。

mysql_truncate_table — 清空表（TRUNCATE TABLE，DDL）

执行 TRUNCATE TABLE 语句，清空整张表数据。属于破坏性操作：默认必须在用户同意后传 confirmDestructive: "Y"/"y"；配置 MYSQL_DDL=true 后可省略。显式传 "N"/"n" 始终取消。支持 ? 参数化占位符。

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | connectionId | string | 是 | — | 连接 ID | | sql | string | 是 | — | TRUNCATE TABLE 语句 | | parameters | array | 否 | [] | ? 占位符参数 | | confirmDestructive | string | 否 | — | 默认需在用户同意后传 Y/y；MYSQL_DDL=true 时可省略；N/n 始终取消 |

返回 { affectedRows, warningStatus }。

mysql_inspect_schema — 探查数据库结构

通过查询 information_schema 获取元数据，按参数组合分三级：

• 无 database 无 table → 列出所有数据库（含字符集、排序规则）
• 有 database 无 table → 列出该库所有表（含类型、引擎、估算行数、注释）
• 有 database 有 table → 返回该表的字段、索引、外键

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | connectionId | string | 是 | 连接 ID | | database | string | 否 | 目标数据库名。不传则列出所有数据库 | | table | string | 否 | 目标表名。不传则列出指定库的所有表 |

返回根据参数组合分别为 { databases }、{ database, tables } 或 { database, table, columns, indexes, foreignKeys }。

安全说明

• 连接密码仅保存在 MCP 进程内存中，不写入文件或日志
• 专用工具按语句类型严格校验：mysql_insert 仅放行 INSERT、mysql_update 仅放行 UPDATE、mysql_delete 仅放行 DELETE、mysql_create_table 仅放行 CREATE TABLE、mysql_alter_table 仅放行 ALTER TABLE、mysql_drop_table 仅放行 DROP TABLE、mysql_truncate_table 仅放行 TRUNCATE TABLE
• mysql_query 仅放行 SELECT / SHOW / DESCRIBE / DESC / EXPLAIN 只读语句，并禁止 SELECT INTO OUTFILE / DUMPFILE
• 删表 / 清空表为破坏性操作，需用户二次确认：mysql_drop_table、mysql_truncate_table 及 mysql_execute 中的 DROP/TRUNCATE 标注 ⚠️ 破坏性操作。默认必须在征得用户明确同意后传入 Y/y，否则服务端拒绝执行
• 跳过 DDL 二次确认：MYSQL_DDL 为可选环境变量，不配置时走 Y/N 确认流程。设置为 true（忽略大小写和首尾空格）可跳过确认，DROP/TRUNCATE 无需 confirmDestructive 直接执行；显式传入 N/n 时始终取消
• 禁用 MySQL 多语句执行（multipleStatements: false），单次调用仅执行一条语句
• SQL 参数均通过 ? 占位符绑定，避免 SQL 注入
• 支持 TLS 加密连接（mysql_connect 中 ssl: true）
• 建议使用最小权限的 MySQL 账号
• 收到 SIGINT / SIGTERM 时自动关闭所有连接池

开发

npm install        # 安装依赖
npm run dev        # 开发模式（tsx 热加载）
npm run build      # 编译 TypeScript → dist/
npm publish        # 发布（自动执行 build）

License

MIT