MySQL MCP Server

MySQL MCP (Model Context Protocol) 服务器，为 AI 助手提供 MySQL 数据库操作能力。通过 MCP 协议暴露 mysql_execute 工具，AI 模型可以直接执行 SQL 查询、读取表结构、进行数据操作。

特性

• 参数化查询：支持 ? 占位符参数，防止 SQL 注入
• 写操作保护：默认禁止 INSERT / UPDATE / DELETE / DROP 等危险操作，需显式开启
• 多语句控制：可配置是否允许多条 SQL 语句在一次调用中执行
• 连接池管理：基于 mysql2 的连接池，高效复用数据库连接
• 结果格式化：查询返回结构化 JSON（含字段信息），写操作返回影响行数、插入 ID 等

前置要求

• Node.js >= 22.0.0
• MySQL 5.7+ / MariaDB 10.2+

安装

npm 全局安装

npm install -g @sanzhangshitou/mysql-mcp-server

项目本地安装

npm install @sanzhangshitou/mysql-mcp-server

从源码安装

git clone https://github.com/sanzhangshitou/mysql-mcp-server.git
cd mysql-mcp-server
npm install
npm run build

配置

环境变量

复制 .env.example 为 .env 并修改：

cp .env.example .env

提示：MYSQL_USER、MYSQL_PASSWORD、MYSQL_DATABASE 三个变量缺一不可，缺少任何一个服务将启动但无法连接数据库。

安全开关说明

使用

命令行

# 开发模式（直接运行 TypeScript）
npm run dev

# 编译为 JavaScript
npm run build

# 运行编译后的服务
npm run start

# 代码检查与格式化
npm run lint
npm run format
npm run check

MCP 客户端配置

在 MCP 客户端（如 Claude Desktop、VS Code Copilot 等）的配置文件中添加：

方式一：使用 node 直接运行

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_user",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database",
        "ALLOW_WRITE": "false"
      }
    }
  }
}

方式二：使用 npx（无需手动安装）

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["@sanzhangshitou/mysql-mcp-server"],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_user",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database",
        "ALLOW_WRITE": "false"
      }
    }
  }
}

MCP 工具

mysql_execute

执行 MySQL SQL 命令。写操作需要 ALLOW_WRITE=true。

输入参数：

调用示例：

{
  "sql": "SELECT * FROM users WHERE id = ?",
  "params": [1]
}

{
  "sql": "INSERT INTO users (name, age) VALUES (?, ?)",
  "params": ["张三", 25]
}

查询返回格式：

{
  "command": "select",
  "sql": "SELECT * FROM users WHERE id = ?",
  "params": [1],
  "result": {
    "type": "rows",
    "rowCount": 1,
    "rows": [{ "id": 1, "name": "张三" }],
    "fields": [
      { "name": "id", "columnType": 3 },
      { "name": "name", "columnType": 253 }
    ]
  }
}

写操作返回格式（需 ALLOW_WRITE=true）：

{
  "command": "insert",
  "sql": "INSERT INTO users (name) VALUES (?)",
  "params": ["李四"],
  "result": {
    "type": "result",
    "affectedRows": 1,
    "insertId": 2,
    "changedRows": 0,
    "warningStatus": 0,
    "info": ""
  }
}

写操作限制

当 ALLOW_WRITE=false（默认）时，以下 SQL 命令将被拒绝执行：

设置 ALLOW_WRITE=true 可允许以上所有操作。

项目结构

mysql-mcp-server/
├── src/
│   ├── index.ts              # MCP 服务器入口（stdio 传输）
│   ├── config.ts             # 环境变量读取与配置验证
│   ├── mysql.ts              # MySQL 连接池初始化（mysql2）
│   ├── sql.ts                # SQL 解析与写命令检测
│   ├── result.ts             # 查询结果格式化
│   └── tools/
│       └── mysqlExecute.ts   # mysql_execute 工具实现
├── dist/                     # TypeScript 编译输出
├── .env.example              # 环境变量配置模板
├── package.json
├── tsconfig.json
└── README.md

安全建议

1. 使用只读账户：在无需写入的场景下，为 MCP 服务创建仅具有 SELECT 权限的 MySQL 用户
2. 保持写保护开启：ALLOW_WRITE 默认为 false，除非确有必要，不要修改
3. 禁止多语句：MYSQL_MULTIPLE_STATEMENTS 保持 false，防止 SQL 注入攻击
4. 不要硬编码凭证：始终通过环境变量或 .env 文件传递数据库连接信息
5. 最小权限原则：为 MCP 服务使用的数据库账户仅授予必要数据库和表的访问权限

相关链接

• GitHub 仓库
• npm 包
• 问题反馈
• Model Context Protocol 文档

License

MIT