MCP MySQL Server

基于 @modelcontextprotocol/sdk + mysql2 的 MySQL MCP Server，让 Claude Code 直接操作 MySQL 数据库。

快速开始

1. 安装

git clone <repo-url> && cd mcp-mysql-server
npm install && npm run build

2. 配置数据库连接

创建 ~/.mcp-mysql/profiles.yml（推荐，支持多环境切换）：

default: dev
profiles:
  dev:
    host: 127.0.0.1
    port: 3306
    user: root
    password: "your_password"
    database: my_app
    readonly: true
  staging:
    host: 192.168.1.100
    user: readonly
    password: "staging_password"
    database: my_app

没有 profiles.yml 时，可通过环境变量 MYSQL_HOST / MYSQL_USER / MYSQL_PASSWORD / MYSQL_DATABASE 配置单连接。

3. 注册到 Claude Code

# 用户级别注册（所有项目可用）
claude mcp add mysql node /absolute/path/to/mcp-mysql-server/dist/index.js -s user

# 或使用 npx（已发布到 npm 时）
claude mcp add mysql npx @huangcaiming5913/mcp-mysql-server -s user

也可以手动编辑 ~/.claude/.mcp.json：

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-mysql-server/dist/index.js"]
    }
  }
}

4. 开始使用

重启 Claude Code 后，直接用自然语言操作数据库：

> 看下有哪些数据库
> dst_goods 里有什么表
> g_goods_manage 的表结构
> 查一下上架中的商品有多少个
> 切换到 staging 环境

11 个工具一览

工具	用途
`list_profiles`	列出所有数据库配置（脱敏，不含密码）
`use_profile`	切换数据库连接（验证连通性后才切换）
`current_profile`	查看当前使用的数据库连接
`query`	执行 SQL（受安全策略控制）
`list_databases`	列出可访问的数据库
`list_tables`	列出表及行数、引擎、注释
`describe_table`	查看字段定义和索引
`explain_query`	执行计划分析 + 优化建议
`generate_schema_doc`	生成 Markdown 表结构文档
`analyze_relations`	分析表间关系（外键 + 索引推断）
`table_stats`	表数据量、存储大小、更新时间

所有数据工具支持可选的 profile 参数，临时使用其他环境查询而不切换当前连接。

配置详解

Profiles 文件（推荐）

路径：~/.mcp-mysql/profiles.yml，可通过 MYSQL_PROFILES_FILE 环境变量覆盖。

每个 profile 可单独设置：

字段	默认值	说明
`host`	—	必填，数据库地址
`port`	`3306`	端口
`user`	—	必填，用户名
`password`	—	必填，密码
`database`	—	默认数据库
`readonly`	`true`	只读模式
`allowDdl`	`false`	允许 DDL（需 readonly=false）
`maxRows`	`1000`	查询最大返回行数
`queryTimeout`	`30000`	查询超时（毫秒）
`poolSize`	`5`	连接池大小

安全建议：

不要将 profiles.yml 提交到代码仓库
Unix/macOS：chmod 600 ~/.mcp-mysql/profiles.yml
Windows：通过文件属性限制访问权限

环境变量

没有 profiles.yml 时回退到环境变量：

变量	必填	默认值	说明
`MYSQL_HOST`	是	`127.0.0.1`	数据库地址
`MYSQL_PORT`	否	`3306`	端口
`MYSQL_USER`	是	—	用户名
`MYSQL_PASSWORD`	是	—	密码
`MYSQL_DATABASE`	否	—	默认数据库
`MYSQL_DSN`	否	—	连接串 `mysql://user:pass@host:port/db`，与上面互斥
`READONLY`	否	`true`	只读模式
`ALLOW_DDL`	否	`false`	允许 DDL
`MAX_ROWS`	否	`1000`	最大返回行数
`QUERY_TIMEOUT`	否	`30000`	超时毫秒
`POOL_SIZE`	否	`5`	连接池大小

优先级：profiles.yml > 环境变量 > DSN。

安全模式

模式	配置	允许的 SQL
只读（默认）	`readonly: true`	SELECT, SHOW, DESCRIBE, EXPLAIN
DML	`readonly: false`	上述 + INSERT, UPDATE, DELETE
DDL	`readonly: false` + `allowDdl: true`	全部

额外保护：

禁止多语句执行（; 分隔的多条语句会被拦截）
SELECT 无 LIMIT 时自动追加 LIMIT {maxRows}

使用示例

# 数据探索
> 看下 dst_goods 数据库有哪些表
> g_goods_manage 的表结构是什么样的
> 查一下上架中的商品有多少个

# 性能分析
> 分析一下这条 SQL 的执行计划：SELECT * FROM g_goods_manage WHERE category_id = 100

# 文档生成
> 帮我生成 g_activity 相关表的表结构文档

# 多环境操作
> 切换到 staging 环境
> 看看哪些表占空间最大
> 用 dev 环境查一下 users 表有多少行（自动使用 profile 参数）

项目结构

src/
  index.ts              # 入口：McpServer + 工具注册 + stdio 传输
  config.ts             # 配置：profiles.yml + 环境变量 + DSN
  connection.ts         # MySQL 连接池管理（按 profile 缓存）
  registry.ts           # 运行时状态：当前 profile + 配置映射
  tools/
    _common.ts          # resolveConn() 按 profile 解析连接
    profile.ts          # list_profiles / use_profile / current_profile
    query.ts            # query
    schema.ts           # list_databases / list_tables / describe_table
    explain.ts          # explain_query
    docs.ts             # generate_schema_doc
    relations.ts        # analyze_relations
    stats.ts            # table_stats
  utils/
    sql-guard.ts        # SQL 安全校验

常见问题

配置修改后不生效？ 修改 profiles.yml 中的字段需重启 Claude Code；但切换 profile 不需要重启，用 use_profile 即可。

密码含特殊字符？ 用 profiles.yml 或环境变量配置，不要用 DSN（DSN 中特殊字符需 URL 编码）。

如何开启写操作？ 设置 readonly: false。DDL 还需 allowDdl: true。生产环境建议保持只读。

如何在多项目中复用？ 注册到用户级别（-s user），所有项目可用。也可在项目 .mcp.json 中单独配置不同连接。