# mcp-mysql-server

**Repository Path**: huangcaiming/mcp-mysql-server

## Basic Information

- **Project Name**: mcp-mysql-server
- **Description**: 这是一个自研的 MySQL MCP Server，基于 `@modelcontextprotocol/sdk` 官方 SDK + `mysql2/promise` 开发。供 Claude Code 通过 MCP 协议直接操作 MySQL 数据库，代码完全自控，无第三方供应链风险。

- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 1
- **Created**: 2026-05-29
- **Last Updated**: 2026-07-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: MCP, MySQL, claude

## README

# MCP MySQL Server

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

> **v1.3.0 新增 PostgreSQL 支持**：通过 `type` 字段或 `PG_*` 环境变量即可连接 PG。
> ⚠️ **PG 支持仅完成基础功能测试，不建议直接用于生产环境。** 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:
    type: mysql              # 数据库类型，默认 mysql，可选 pg
    host: 127.0.0.1
    port: 3306               # MySQL 默认 3306
    user: root
    password: "your_password"
    database: my_app
    readonly: true
  staging:
    type: mysql
    host: 192.168.1.100
    user: readonly
    password: "staging_password"
    database: my_app
  pg-local:                  # PostgreSQL 示例
    type: pg
    host: 127.0.0.1
    port: 5432               # PG 默认 5432
    user: postgres
    password: "pg_password"
    database: my_pg_db
```

> 没有 profiles.yml 时，可通过环境变量配置单连接：
> - MySQL：`MYSQL_HOST` / `MYSQL_USER` / `MYSQL_PASSWORD` / `MYSQL_DATABASE`
> - PostgreSQL：`PG_HOST` / `PG_USER` / `PG_PASSWORD` / `PG_DATABASE`
> - 系统检测到 `PG_*` 变量且无 `MYSQL_*` 变量时自动识别为 PG 类型

### 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 个工具一览

| 工具 | 用途 | MySQL | PostgreSQL |
|------|------|:-----:|:----------:|
| `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` 参数，临时使用其他环境查询而不切换当前连接。

> **PostgreSQL 注意事项**：
> - PG 是 database → schema → table 三层结构。profile 中的 `database` 用于连接，工具调用时的 `database` 参数语义为 schema 名，默认为 `public`。
> - `list_databases` 返回 PG 实例中的所有数据库。
> - `explain_query` 使用 `EXPLAIN (FORMAT JSON)` 并解析执行计划树。

## 配置详解

### Profiles 文件（推荐）

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

每个 profile 可单独设置：

| 字段 | 默认值 | 说明 |
|------|--------|------|
| `type` | `mysql` | 数据库类型：`mysql` 或 `pg` |
| `host` | — | 必填，数据库地址 |
| `port` | 按类型自动 | MySQL=`3306`，PG=`5432` |
| `user` | — | 必填，用户名 |
| `password` | — | 必填，密码 |
| `database` | — | 默认数据库（PG 中为连接的数据库名） |
| `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 和 PG 各有独立变量名：

**MySQL 环境变量：**

| 变量 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `MYSQL_HOST` | 是 | `127.0.0.1` | 数据库地址 |
| `MYSQL_PORT` | 否 | `3306` | 端口 |
| `MYSQL_USER` | 是 | — | 用户名 |
| `MYSQL_PASSWORD` | 是 | — | 密码 |
| `MYSQL_DATABASE` | 否 | — | 默认数据库 |
| `MYSQL_DSN` | 否 | — | 连接串 `mysql://user:pass@host:port/db`，与上面互斥 |

**PostgreSQL 环境变量：**

| 变量 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `PG_HOST` | 是 | `127.0.0.1` | 数据库地址 |
| `PG_PORT` | 否 | `5432` | 端口 |
| `PG_USER` | 是 | — | 用户名 |
| `PG_PASSWORD` | 是 | — | 密码 |
| `PG_DATABASE` | 否 | — | 默认数据库 |
| `PG_DSN` | 否 | — | 连接串 `postgresql://user:pass@host:port/db`，与上面互斥 |

**通用环境变量：**

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `READONLY` | `true` | 只读模式 |
| `ALLOW_DDL` | `false` | 允许 DDL |
| `MAX_ROWS` | `1000` | 最大返回行数 |
| `QUERY_TIMEOUT` | `30000` | 超时毫秒 |
| `POOL_SIZE` | `5` | 连接池大小 |
| `DB_TYPE` | 自动 | 强制类型：`mysql` / `pg`（自动检测优先） |

自动检测规则：检测到 `PG_*` 变量且无 `MYSQL_*` 变量时默认 PG，反之默认 MySQL。

优先级：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 (MySQL/PG 双套)
  connection.ts         # 连接池管理：mysql2 + pg 统一 dbQuery()
  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（PG 使用 EXPLAIN FORMAT JSON）
    docs.ts             # generate_schema_doc
    relations.ts        # analyze_relations（PG 使用 pg_catalog）
    stats.ts            # table_stats（PG 使用 pg_class/pg_stat_user_tables）
  utils/
    sql-guard.ts        # SQL 安全校验
    pg-sql.ts           # PostgreSQL 专用 SQL 查询构建器
```

## 更新日志

### v1.3.0（2026-07-13）
- ✨ **新增 PostgreSQL 支持**：通过 `type: pg` 或 `PG_*` 环境变量连接 PG
- ✨ 11 个工具全部支持 MySQL 和 PostgreSQL 双数据库
- ✨ 统一的 `dbQuery()` 抽象层屏蔽底层驱动差异
- ⚠️ **PG 支持仅完成基础功能测试**，不建议直接用于生产环境
- 🔧 MySQL 部分完全向后兼容，无需改动现有配置

### v1.2.1 及更早
- MySQL MCP Server 基础功能

## 常见问题

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

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

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

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