mysql-mcp-server

一个基于 stdio 的只读 MySQL MCP Server。它为支持 Model Context Protocol 的客户端提供 MySQL 查询、库表浏览和表结构查看能力，并在执行前对 SQL 做只读校验。

功能特性

• 通过 MCP stdio transport 暴露 MySQL 只读工具
• 支持 SELECT、WITH SELECT、SHOW、DESCRIBE / DESC 和安全的 EXPLAIN
• 拒绝多语句、写入语句、管理语句、锁相关语句和高风险函数
• 使用 START TRANSACTION READ ONLY 执行查询，并在查询后回滚事务
• 支持结果行数上限、查询超时、连接池和可选 SSL

环境要求

• Node.js >= 20
• MySQL 兼容数据库
• 一个建议只授予读取权限的 MySQL 用户

安装与构建

npm install
npm run build

本地开发可使用：

npm run dev

构建后启动：

npm start

使用 MCP Inspector 调试：

npm run inspect

配置

服务通过环境变量读取 MySQL 连接配置。可以参考 .env.example：

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=readonly_user
MYSQL_PASSWORD=change-me
MYSQL_DATABASE=
MYSQL_SSL=false
MYSQL_SSL_REJECT_UNAUTHORIZED=true
MYSQL_CONNECTION_LIMIT=5
MYSQL_CONNECT_TIMEOUT_MS=10000
MYSQL_QUERY_TIMEOUT_MS=30000
MYSQL_MAX_ROWS=500

变量	必填	默认值	说明
MYSQL_HOST	否	127.0.0.1	MySQL 主机
MYSQL_PORT	否	3306	MySQL 端口
MYSQL_USER	是	-	MySQL 用户名
MYSQL_PASSWORD	是	-	MySQL 密码
MYSQL_DATABASE	否	-	默认数据库，留空则不指定
MYSQL_SSL	否	false	是否启用 SSL
MYSQL_SSL_REJECT_UNAUTHORIZED	否	true	SSL 是否校验证书
MYSQL_CONNECTION_LIMIT	否	5	连接池连接数上限
MYSQL_CONNECT_TIMEOUT_MS	否	10000	建连超时时间，单位毫秒
MYSQL_QUERY_TIMEOUT_MS	否	30000	查询超时时间，单位毫秒
MYSQL_MAX_ROWS	否	500	单次返回的最大行数

布尔值支持 1、true、yes、on 和 0、false、no、off。

MCP 客户端配置示例

发布到 npm 后，可以在 MCP 客户端配置中加入：

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": [
        "-y",
        "@xujcbiz/mysql-mcp-server"
      ],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "readonly_user",
        "MYSQL_PASSWORD": "change-me",
        "MYSQL_DATABASE": "",
        "MYSQL_SSL": "false",
        "MYSQL_MAX_ROWS": "500"
      }
    }
  }
}

也可以参考仓库中的 mcp-config.example.json。本地开发调试时，可以先执行 npm run build，再临时使用 node D:/project/mysql-mcp-server/dist/index.js 这种绝对路径方式。

可用工具

mysql_query

执行只读 SQL。

输入：

{
  "sql": "SELECT * FROM users LIMIT 10",
  "maxRows": 100
}

maxRows 可选，不能超过 MYSQL_MAX_ROWS。

mysql_list_databases

列出当前 MySQL 用户可见的数据库。

输入：

{
  "pattern": "app_%"
}

pattern 可选，使用 MySQL LIKE 语法。

mysql_list_tables

列出当前或指定数据库下的表和视图。

输入：

{
  "database": "app_db",
  "pattern": "user%",
  "includeViews": true
}

mysql_describe_table

查看表字段信息，可选返回索引信息。

输入：

{
  "database": "app_db",
  "table": "users",
  "includeIndexes": true
}

mysql_connection_info

返回当前数据库、连接用户、有效用户和 MySQL 版本。

输入：

{}

返回格式

查询类工具会返回 JSON 文本和结构化结果，结构大致如下：

{
  "rows": [],
  "fields": [],
  "rowCount": 0,
  "truncated": false,
  "executionMs": 0
}

• rows：返回的数据行
• fields：字段名列表
• rowCount：查询得到的总行数
• truncated：结果是否因 maxRows 被截断
• executionMs：执行耗时，单位毫秒

只读安全策略

服务会在执行前对 SQL 做校验：

• 仅允许 SELECT、WITH SELECT、SHOW、DESCRIBE / DESC 和 EXPLAIN
• 禁止多条 SQL 语句
• 禁止 INSERT、UPDATE、DELETE、ALTER、DROP、CREATE、TRUNCATE 等写入或管理语句
• 禁止 SELECT ... INTO、FOR UPDATE、LOCK IN SHARE MODE 等可能产生副作用或锁的语法
• 禁止 SLEEP、BENCHMARK、GET_LOCK 等高风险函数

仍然建议在数据库侧使用只读账号，并只授予必要库表的读取权限。

项目结构

src/
  config.ts      环境变量配置读取与校验
  database.ts    MySQL 连接池和只读查询封装
  index.ts       MCP Server 入口和工具注册
  sqlSafety.ts   SQL 只读校验与标识符转义

常用命令

npm run build    # 编译 TypeScript 到 dist/
npm run dev      # 使用 tsx 运行源码
npm start        # 运行 dist/index.js
npm run inspect  # 使用 MCP Inspector 调试