@qdkj/mysql-mcp-server

MySQL 数据库操作 MCP 服务端 · 通过 MCP 协议让 AI 客户端直接查询/操作你的 MySQL

1. 🚀 MCP 使用方法 + JSON 配置

把这个 JSON 整段粘到你 MCP 客户端（Cursor / Claude Desktop / CodeBuddy 等）的配置里即可使用。npx -y @qdkj/mysql-mcp-server@latest 会在首次启动时自动拉取最新版本。

最简 JSON

{
  "mcpServers": {
    "mysql-sql-exec-qdkj": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@qdkj/mysql-mcp-server@latest"],
      "env": {
        "MYSQL_HOST": "你的MySQL地址",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "你的用户名",
        "MYSQL_PASSWORD": "你的密码",
        "MYSQL_DATABASE": "你的数据库名",
        "MYSQL_ALLOW_WRITE": "true",
        "MYSQL_ALLOW_DDL": "true"
      }
    }
  }
}

把 env 里 你的xxx 改成自己的数据库信息即可。安全约束相关变量默认 false（只读 + 禁止 DDL），需要放开时改 true 重启服务。

环境变量完整说明

| 变量 | 必填 | 默认 | 说明 | |------|------|------|------| | MYSQL_HOST | ✅ | — | 数据库主机 | | MYSQL_PORT | | 3306 | 数据库端口 | | MYSQL_USER | ✅ | — | 数据库用户 | | MYSQL_PASSWORD | ✅ | — | 数据库密码 | | MYSQL_DATABASE | ✅ | — | 数据库名 | | MYSQL_ALLOW_WRITE | | true | 是否允许 INSERT/UPDATE/DELETE；设 false 即只读；改值需重启服务 | | MYSQL_ALLOW_DDL | | true | 是否允许 CREATE/ALTER/DROP/TRUNCATE/RENAME；设 false 即禁 DDL；改值需重启服务 |

工具与客户端通信

服务通过 stdio 与 MCP 客户端通信，所有日志写到 stderr，不污染 stdout。客户端工具调用 → JSON-RPC over stdin → 服务执行 → JSON-RPC over stdout 返回结果。

2. 🛠️ 工具列表

服务对外暴露 4 个 MCP 工具，AI 客户端会看到这些工具并可在对话中调用。

2.1 list_tables

• 功能：获取当前数据库中的所有表名和表备注
• 参数：无
• 返回：JSON 数组，每个元素含 table_name / table_comment
• 示例返回：

  [
    { "table_name": "users", "table_comment": "用户表" },
    { "table_name": "orders", "table_comment": "订单表" }
  ]

2.2 get_table_structure

• 功能：查询一个或多个表的详细结构信息
• 参数：
  • tables（必填）：表名，多个表用逗号分隔（如 users,orders,products）
• 返回：JSON 数组，每个元素含 table_name 与 columns 列表
• 列信息字段：column_name / data_type / is_nullable / column_key / column_default / column_comment / extra

2.3 exec_sql

• 功能：执行预编译 SQL，支持 SELECT / INSERT / UPDATE / DELETE 等增删改查
• 参数：
  • sql（必填）：预编译 SQL，? 作为占位符
  • params（可选）：参数数组，与 ? 一一对应
• 返回：JSON 数组，每行为字段名到值的映射（{ "id": 1, "username": "alice" }）
• 安全约束：
  • 默认只允许 SELECT / SHOW / EXPLAIN / DESCRIBE / DESC
  • 遇到变更语句（如 INSERT）且未开启写权限 → 不执行，原样返回并提示手动跑
  • 命中 DDL 关键字 → 提示改用 ddl_exec 工具
  • 默认允许；设 MYSQL_ALLOW_WRITE=false 即只读

2.4 ddl_exec

• 功能：执行 DDL 语句（表结构修改），仅支持 CREATE / ALTER / DROP / TRUNCATE / RENAME
• 参数：
  • sql（必填）：DDL 语句
  • params（可选）：参数列表（用于预编译）
• 返回：执行结果，含 affected_rows / message / success
• 安全约束：
  • 默认不允许执行 DDL
  • 默认允许；设 MYSQL_ALLOW_DDL=false 即禁 DDL

3. 💻 本地调试

3.1 全局安装直接调用（推荐）

npm install -g @qdkj/mysql-mcp-server --registry=https://registry.npmjs.org/

# 验证 bin 可用
qdkj-mysql-mcp-server
# 应该立即进入 stdio 监听，Ctrl+C 退出

3.2 源码本地构建

git clone <本仓库>
cd db/mysql/sql_exec_node
npm install
npm run build           # 产物在 dist/

# 方式 A：跑编译产物
node dist/index.js

# 方式 B：直接跑源码（需要 tsx）
npx tsx src/index.ts

3.3 MCP 客户端调试技巧

• 日志写在 stderr，需要看时把 MCP 客户端的 stderr 重定向到文件
• 想验证 JSON 配置：先单独启一次 qdkj-mysql-mcp-server，手敲 JSON-RPC 消息看响应
• 想确认工具是否注册：让 AI 客户端列出可用工具，应该看到上述 4 个

4. 🔧 二次开发

⚠️ 本 npm 包只包含编译产物 dist/ 和 README.md，不含源码。源码在 GitHub 仓库的 db/mysql/sql_exec_node/src/ 下，便于二次开发但不影响安装速度。

4.1 仓库结构

db/mysql/sql_exec_node/
├── src/                 # TypeScript 源码（编译前）
│   ├── config.ts        # 环境变量解析、stderr 日志
│   ├── db.ts            # mysql2 连接池 + SQL 拦截器
│   ├── server.ts        # 4 个工具注册到 MCP Server
│   └── index.ts         # 入口（含 shebang）
├── dist/                # 编译产物（npm 包内）
├── package.json         # 1.0.3
└── README.md            # 本文件

4.2 改完如何打包并测试

cd db/mysql/sql_exec_node
npm install
npm run build           # 产出 dist/

# 本地测试：把你的 mcp_config.json 里 command 改成 node，args 指向新 dist/index.js
# 或直接：node dist/index.js（带环境变量）

4.3 发布新版本

参考仓库根 PUBLISH.md —— 使用 npm publish --registry=https://registry.npmjs.org/ --access public 即可，token 已配置在 ~/.npmrc。

⚠️ 注意事项

• 确保 MySQL 服务可连且账号有权限访问目标数据库
• 环境变量必须正确设置，否则服务启动失败
• MYSQL_ALLOW_WRITE / MYSQL_ALLOW_DDL 改值后必须重启 MCP 客户端才生效
• 日志通过 stderr 输出，便于排查，不影响 MCP 协议（stdout）通信

版本 1.0.3 · 最后更新 2026-08-13