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 中单独配置不同连接。