# mysql-mcp

**Repository Path**: creekmoon/mysql-mcp

## Basic Information

- **Project Name**: mysql-mcp
- **Description**: fork @davewind/mysql-mcp-server
Mysql只读MCP
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-03
- **Last Updated**: 2026-08-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mysql-mcp

> **开箱即用：已在 Docker Hub 发布公开镜像，推荐直接拉取运行。**  
> 镜像仓库：[yinjiangyue/mysql-mcp-server](https://hub.docker.com/repository/docker/yinjiangyue/mysql-mcp-server/)  
> 拉取命令：`docker pull yinjiangyue/mysql-mcp-server:v1.2.0`

> 声明：初版 FORK 自 [@davewind/mysql-mcp-server](https://github.com/dave-wind/mysql-mcp-server)，由本人做了部分重构，请勿与上游 npm 包直接等同。

给 LLM 提供 **MySQL 只读访问**：一个进程挂多个环境（如 prod / dev），每个环境对应一个 MySQL 实例。能看库表结构，能跑 SELECT，不能改数据、不能改表结构。

> **给 AI 部署用：** 将 Gitee 上的 [`llms.txt`](https://gitee.com/creekmoon/mysql-mcp/blob/master/llms.txt) 链接提供给大模型，按其中步骤完成 Docker Compose 部署与 MCP 接入。Compose 示例见 [`example/docker-compose.yml`](https://gitee.com/creekmoon/mysql-mcp/blob/master/example/docker-compose.yml)。

```
  +-------------------+      MCP       +---------------------+
  |  LLM / MCP Client | <------------> |  mysql-mcp          |
  +-------------------+  http / stdio  +----------+----------+
                                                  |
                         environment=prod / dev   |
                    +-----------------------------+-----------------------------+
                    |                             |                             |
           list_environments              list_databases                  list_tables
            (列出已配置环境)                 (列出数据库)                    (列出表)
                                                      |
                                                    query
                                          (SELECT / WITH / 子查询)
```

---

## AI 部署文档（llms.txt）

若希望大模型**直接帮你部署**本服务，把下面链接交给 AI 即可（无需通读 README）：

**https://gitee.com/creekmoon/mysql-mcp/blob/master/llms.txt**

- 面向 LLM 的逐步部署说明
- 推荐方式与 [`example/`](https://gitee.com/creekmoon/mysql-mcp/tree/master/example) 一致：Docker Compose + `sources.json` 多环境配置
- 含镜像地址、环境变量、MCP 工具用法、验证步骤与常见错误

相关源码文件（可一并提供给 AI 参考）：

| 文件 | Gitee 地址 |
|------|------------|
| AI 部署文档 | https://gitee.com/creekmoon/mysql-mcp/blob/master/llms.txt |
| Compose 示例 | https://gitee.com/creekmoon/mysql-mcp/blob/master/example/docker-compose.yml |
| 数据源配置示例 | https://gitee.com/creekmoon/mysql-mcp/blob/master/example/sources.json |

用法示例：在对话中粘贴 `llms.txt` 的 Gitee 链接，并说明「按此文档部署 mysql-mcp」。

---

## 你能用它做什么

1. 让 AI 助手先摸清某个环境下有哪些库、哪些表、字段是什么
2. 让 AI 在指定环境执行只读 SQL，查数据做问答 / 排障
3. 用 HTTP 做中央化部署（多客户端并发）；也支持 stdio 本地直连

**不能做什么：** INSERT / UPDATE / DELETE、建改删表、往服务器写文件。

**连接与权限边界：** 每个环境连的是 MySQL **实例**（推荐连接串只写到 `host:port`，例如 `mysql://user:password@host:3306`）。不要用连接串里的 `/database` 做库级隔离——那不是本 MCP 的职责。需要限制可见/可查范围时，请在 MySQL 侧用只读账号与 GRANT 控制；生产环境务必给账号加只读权限，作为最后一道防线。

---

## 公开 Docker 镜像

本项目的官方镜像托管在 Docker Hub，**公开可拉取**，无需登录或私有仓库权限：

| 项 | 说明 |
|------|------|
| 仓库地址 | [https://hub.docker.com/repository/docker/yinjiangyue/mysql-mcp-server/](https://hub.docker.com/repository/docker/yinjiangyue/mysql-mcp-server/) |
| 镜像名 | `yinjiangyue/mysql-mcp-server` |
| 推荐标签 | `v1.2.0`（可用标签以 Docker Hub 为准） |

```bash
docker pull yinjiangyue/mysql-mcp-server:v1.2.0
```

单容器快速启动：

```bash
docker run -d --name mysql-mcp -p 12024:12024 \
  -e MCP_SOURCES_JSON='{"environments":{"prod":{"url":"mysql://user:password@host:3306","description":"生产环境"}}}' \
  yinjiangyue/mysql-mcp-server:v1.2.0
```

---

## 快速启动（首选：Docker）

仓库自带 Compose 示例，可直接使用：

```bash
cd example
# 修改 sources.json 中的连接串
docker compose up -d
```

示例文件位于 [`example/`](https://gitee.com/creekmoon/mysql-mcp/tree/master/example) 目录：

- [`example/docker-compose.yml`](https://gitee.com/creekmoon/mysql-mcp/blob/master/example/docker-compose.yml)
- [`example/sources.json`](https://gitee.com/creekmoon/mysql-mcp/blob/master/example/sources.json)

### 1. 写数据源配置 `sources.json`

```json
{
  "environments": {
    "prod": {
      "url": "mysql://user:password@prod-host:3306",
      "description": "生产环境，订单与用户库"
    },
    "dev": {
      "url": "mysql://user:password@dev-host:3306",
      "description": "开发环境，测试数据"
    }
  }
}
```

环境名须匹配 `^[a-z][a-z0-9_]{0,31}$`（小写字母开头，仅字母数字下划线，最长 32 字符）。完整示例见 [`sources.example.json`](https://gitee.com/creekmoon/mysql-mcp/blob/master/sources.example.json) 或 [`example/sources.json`](https://gitee.com/creekmoon/mysql-mcp/blob/master/example/sources.json)。

### 2. 写 `docker-compose.yml`

也可自行编写，参考如下（镜像来自上述公开仓库）：

```yaml
# 示例：拉取并运行 mysql-mcp
# 1. 按需修改 sources.json 中的连接串（推荐只写到 host:port，不要带 /database）
# 2. docker compose up -d
services:
  mysql-mcp:
    image: yinjiangyue/mysql-mcp-server:v1.2.0
    ports:
      - "12024:12024"
    volumes:
      - ./sources.json:/app/sources.json:ro
    environment:
      MCP_SOURCES_FILE: /app/sources.json
      MCP_TRANSPORT: http
      MCP_PORT: "12024"
      MYSQL_CONNECTION_LIMIT: "20"
      MYSQL_QUEUE_LIMIT: "100"
      MYSQL_QUERY_TIMEOUT_MS: "20000"
      MYSQL_KILL_ON_TIMEOUT: "1"
```

也可不挂文件，改用内联 JSON：

```yaml
environment:
  MCP_SOURCES_JSON: '{"environments":{"prod":{"url":"mysql://user:password@host:3306","description":"生产环境"}}}'
```

`MCP_SOURCES_FILE` 优先于 `MCP_SOURCES_JSON`。

### 3. 启动

```bash
docker compose up -d
```

- 健康检查：`http://localhost:12024/health`
- MCP 地址：`http://localhost:12024/mcp`

### 4. 接到 Cursor 等客户端（HTTP）

```json
{
  "mcpServers": {
    "mysql": {
      "transport": "http",
      "url": "http://localhost:12024/mcp"
    }
  }
}
```

> 具体字段名以你使用的客户端为准；需支持 MCP Streamable HTTP。

---

## 让 AI 这样用

建议提问顺序（每次调用都要带上环境，**第一步除外**）：

0. 「当前有哪些环境」→ 走 `list_environments`（无参）
1. 「在 prod 列出有哪些数据库」→ 走 `list_databases`，`environment=prod`
2. 「列出 prod 某某库里的表」→ 走 `list_tables`（传入 `environment` 与 `database`）
3. 「在 prod 查一下某某条件的数据」→ 走 `query`（只会跑只读 SQL；表名用 `database.table`）

推荐用法下：`list_tables` 始终传入 `database`；`query` 的 SQL 始终使用全限定表名 `database.table`。

### 可用工具

| 工具 | 作用 | 输入 |
|------|------|------|
| `list_environments` | 列出已配置的所有环境及业务描述 | 无 |
| `list_databases` | 列出指定环境实例中的数据库 | `environment`（必填，enum） |
| `list_tables` | 列出某库中的表 | `environment`（必填）；`database`（应传入；若该环境连接串写了库名仍可省略，但不推荐） |
| `query` | 执行只读 SQL | `environment`（必填）；`sql`（必填；推荐 `database.table`） |

`environment` 的可选值与 `list_environments` 返回的 `name` 一致；各工具 description 也会列出「环境名（描述）」。

`query` 规则一览：

- 只允许 `SELECT` / `WITH`（CTE）/ 子查询开头
- 拦截 `INTO OUTFILE` / `INTO DUMPFILE`
- 在 `START TRANSACTION READ ONLY` 中执行
- 受查询超时限制（见下方环境变量）

---

## 环境变量

| 变量 | 说明 | 默认 |
|------|------|------|
| `MCP_SOURCES_FILE` | 多环境配置文件路径（JSON） | （与下一行二选一，本项优先） |
| `MCP_SOURCES_JSON` | 多环境配置的内联 JSON 字符串 | （与上一行二选一） |
| `MCP_TRANSPORT` | `http` 或 `stdio` | `http` |
| `MCP_PORT` / `PORT` | HTTP 监听端口 | `12024` |
| `MYSQL_CONNECTION_LIMIT` | 每个环境连接池大小（全局共用同一套数值） | `20` |
| `MYSQL_QUEUE_LIMIT` | 连接池等待队列上限 | `100` |
| `MYSQL_QUERY_TIMEOUT_MS` | 单条查询超时（毫秒）；`0` 关闭 | `20000` |
| `MYSQL_KILL_ON_TIMEOUT` | 超时后是否用另一条连接发 `KILL QUERY` 主动停服务端查询；`0`/`false`/`off` 关 | `1` |

超时策略：每个环境启动时独立探测库版本。MySQL 5.7+ 用服务端 `MAX_EXECUTION_TIME` 作 SELECT 第一道；应用层计时到点后用另一条连接发 `KILL QUERY` 主动停服务端查询（可由 `MYSQL_KILL_ON_TIMEOUT` 关闭，仅作兜底，失败静默降级记日志）。MariaDB / 旧版本同样走应用层计时 + KILL。探测失败不阻断启动。

---

## HTTP 端点

默认 HTTP 模式，MCP 流量都走 `/mcp`：

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/mcp` | 建立 SSE 流 |
| `POST` | `/mcp` | 发送 JSON-RPC 消息 |
| `GET` | `/health` | 健康检查 |

按会话隔离：每个客户端独立会话，支持 Cursor 等并发与重连。各会话共享同一份多环境连接池。

---

## 备选：源码本地启动（非首选）

需要改代码或不用中央镜像时再走这条路。需要 Node.js 18+。

```bash
npm install
npm run build

# HTTP 模式（默认，端口 12024）
MCP_SOURCES_FILE=./sources.json node build/index.js

# stdio 模式
MCP_SOURCES_FILE=./sources.json MCP_TRANSPORT=stdio node build/index.js
```

命令行第一个参数也可指定传输模式（`http` / `stdio`），覆盖 `MCP_TRANSPORT`。

**stdio 客户端配置示例：**

```json
{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["D:/path/to/mysql-mcp/build/index.js"],
      "env": {
        "MCP_SOURCES_FILE": "D:/path/to/mysql-mcp/sources.json",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}
```

**本地构建镜像（自行构建，非 Docker Hub 公开镜像）：**

```bash
docker build -t mysql-mcp:local .
docker run -d -p 12024:12024 \
  -v "$PWD/sources.json:/app/sources.json:ro" \
  -e MCP_SOURCES_FILE=/app/sources.json \
  mysql-mcp:local
```

---

## 自测（可选）

```bash
# 单元测试
npm test

# Inspector（需先设置 MCP_SOURCES_FILE 或 MCP_SOURCES_JSON）
npx @modelcontextprotocol/inspector@0.10.2 build/index.js
```

集成测试仍用 `MYSQL_URL` 作为测试实例连接串，启动时写入 `MCP_SOURCES_JSON` 的 prod 环境：

```bash
MYSQL_URL=mysql://user:pass@host:3306 npm run test:integration
```

---

## 许可证

MIT