# MCP MySQL Server

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

## 快速开始

### 1. 安装

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

### 2. 配置数据库连接

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

```yaml
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

```bash
# 用户级别注册（所有项目可用）
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`：

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