@mwee/mysql-mcp-server

一个支持多实例的 MySQL MCP Server，让 AI Agent 能在对话中直接查询多个 MySQL 数据库。

功能特性

• 多实例管理 — 一个进程管理多个 MySQL 实例，按名称切换
• 纯只读 — 仅允许 SELECT / SHOW / DESCRIBE / EXPLAIN，自动拦截写操作
• 懒连接 — 首次查询时才建连接，不浪费资源
• 安全 — 密码支持环境变量引用，配置文件不含明文密码
• 零安装 — npx @mwee/mysql-mcp-server@latest 直接运行

提供的工具

| 工具 | 说明 | |------|------| | list_instances | 列出所有已配置实例 | | instance_status | 检查实例连接状态和版本 | | list_databases | 列出实例下所有数据库 | | list_tables | 列出指定库的所有表（含注释） | | describe_table | 查看表结构 | | show_create_table | 查看建表语句 | | show_indexes | 查看表索引 | | mysql_query | 执行只读 SQL 查询 | | explain_query | EXPLAIN 执行计划分析 | | show_variables | 查询系统变量 | | show_status | 查询服务器状态 | | show_processlist | 查看当前连接 |

环境要求

• Node.js >= 20
• MySQL 5.7+（推荐 8.0+）

快速开始

1. 创建配置文件

mkdir -p ~/.mysql-mcp-server

创建 ~/.mysql-mcp-server/db-config.json：

{
  "defaults": {
    "user": "readonly",
    "password": "${MYSQL_READONLY_PWD}",
    "port": 3306,
    "queryTimeout": 30000,
    "maxRows": 1000,
    "poolSize": 5
  },
  "instances": {
    "prod": { "host": "10.1.1.2", "desc": "生产库" },
    "test": { "host": "10.2.2.2", "desc": "测试库" }
  }
}

配置说明：

• defaults — 公共默认值，每个实例自动继承
• instances — 实例列表，每个实例可覆盖 defaults 中的任意字段
• ${MYSQL_READONLY_PWD} — 环境变量占位符，运行时自动替换

单个实例覆盖示例：

"pay_db": {
  "host": "10.5.5.2",
  "port": 3307,
  "user": "pay_readonly",
  "password": "${MYSQL_PAY_PWD}",
  "desc": "支付库（独立账号）"
}

2. 设置密码环境变量

Windows (永久生效):

setx MYSQL_READONLY_PWD "your_password"

Linux / Mac:

echo 'export MYSQL_READONLY_PWD="your_password"' >> ~/.bashrc
source ~/.bashrc

3. 在 MCP 客户端中注册

Aone Copilot — 编辑 ~/.aone_copilot/mcp_servers.json：

{
  "mcpServers": {
    "mysql-mcp-server": {
      "enabled": true,
      "type": "stdio",
      "command": "npx",
      "args": ["@mwee/mysql-mcp-server@latest"]
    }
  }
}

Cursor / Claude Desktop — 编辑对应配置文件：

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["@mwee/mysql-mcp-server@latest"]
    }
  }
}

注册后重启客户端即可使用。

4. 测试（可选）

npx @modelcontextprotocol/inspector npx @mwee/mysql-mcp-server@latest

配置文件查找优先级

1. 环境变量 MYSQL_MCP_CONFIG 指定的路径
2. 命令行参数 --config <path>
3. ~/.mysql-mcp-server/db-config.json（推荐）
4. 当前工作目录下的 db-config.json

安全说明

• 仅允许 SELECT, SHOW, DESCRIBE, DESC, EXPLAIN, USE 操作
• 自动拦截 INSERT, UPDATE, DELETE, DROP, ALTER 等写操作
• 查询结果默认最多返回 1000 行（可通过 maxRows 配置）
• 密码通过环境变量注入，db-config.json 不入 Git

项目结构

mysql-mcp-server/
├── package.json              # 依赖声明
├── src/
│   ├── index.js              # MCP Server 主入口
│   ├── config.js             # 配置加载
│   ├── pool-manager.js       # 连接池管理
│   ├── sql-guard.js          # SQL 安全校验
│   └── tools/
│       ├── instance-tools.js # 实例管理工具
│       ├── schema-tools.js   # Schema 查询工具
│       ├── query-tools.js    # SQL 查询工具
│       └── system-tools.js   # 系统信息工具
├── db-config.example.json    # 配置模板
├── db-config.json            # 实际配置（不入 Git）
├── .gitignore
└── README.md