npm package: @ouyanglouzhu/mysql
Description: MySQL MCP Server (Python) - 通过 MCP 查询 MySQL，支持单连接或连接文件（如 Airflow connections.json），供 Cursor/Claude 等使用。
Latest version: 0.1.0

# MySQL MCP Server（Python）

基于 [Model Context Protocol](https://modelcontextprotocol.io/) 的 MySQL 服务端，供 Cursor 等客户端通过工具调用执行查询、查看库表与建表语句。

**配置方式二选一**：  
- **单连接**：通过环境变量传入一个 MySQL 连接。  
- **连接文件**：通过环境变量指定 JSON 文件路径（如 Airflow `connections.json`），解析其中 `conn_type` 为 `mysql` 的条目；根据用户提问选择不同连接（如「查 dw_misc 库」→ 使用连接名 `dw_misc`）。

**分发方式**：仅通过 **npm** 发布，Python 源码与依赖随包提供。用户 `npm install` 后由 postinstall 自动安装 Python 依赖。

## 功能（Tools）

| 工具名 | 说明 |
|--------|------|
| `mysql_list_connections` | 列出当前可用连接名称，供后续查询时选择 |
| `mysql_query` | 在指定连接上执行只读 SELECT，可选 connection、database |
| `mysql_list_databases` | 列出指定连接下的数据库 |
| `mysql_list_tables` | 列出指定连接、指定库下的表 |
| `mysql_describe_table` | 获取表结构 |
| `mysql_get_create_table` | 获取建表语句（SHOW CREATE TABLE） |

## 环境变量

### 方式一：单连接

| 变量 | 说明 | 默认 |
|------|------|------|
| `MYSQL_HOST` | 主机 | `localhost` |
| `MYSQL_PORT` | 端口 | `3306` |
| `MYSQL_USER` | 用户名 | 空 |
| `MYSQL_PASSWORD` | 密码 | 空 |
| `MYSQL_DATABASE` | 默认数据库 | 空 |
| `MYSQL_CHARSET` | 字符集 | `utf8mb4` |

此时所有工具使用唯一连接，`connection` 可省略或传 `default`。

### 方式二：连接文件

| 变量 | 说明 |
|------|------|
| `MYSQL_CONNECTIONS_FILE` | JSON 文件路径（绝对或相对当前工作目录）。格式：`{ "conn_id": { "conn_type": "mysql", "host": "...", "port": 3306, "login": "...", "password": "...", "schema": "..." }, ... }`。仅解析 `conn_type` 为 `mysql` 的条目；`extra` 可为 JSON 字符串，如 `{"charset":"utf8mb4"}`。 |

与 Airflow `connections.json` 兼容：字段 `login`/`schema` 对应用户名/数据库，若存在 `extra` 会解析 `charset`。

根据用户提问选择连接：先调用 `mysql_list_connections` 查看可用连接名，再在 `mysql_query`、`mysql_list_tables` 等中传入 `connection` 参数（如 `dw_misc`、`afe_core`）。

## 安装与使用

### 通过 npm（推荐）

```bash
npm install @ouyanglouzhu/mysql
```

安装时 postinstall 会自动执行 `pip install -r requirements.txt`（需本机 Python 3.10+）。

### 在 Cursor 中配置 MCP

**单连接示例**（`.cursor/mcp-config.json` 或全局 MCP 配置）：

```json
{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@ouyanglouzhu/mysql"],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "mydb"
      }
    }
  }
}
```

**连接文件示例**（使用项目内 Airflow 配置）：

```json
{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@ouyanglouzhu/mysql"],
      "env": {
        "MYSQL_CONNECTIONS_FILE": "D:/code/python/dw-sit/airflow/dags/config/sit/connections.json"
      }
    }
  }
}
```

或使用相对路径（相对于 Cursor 打开的项目根目录或 MCP 进程工作目录）：

```json
"env": {
  "MYSQL_CONNECTIONS_FILE": "airflow/dags/config/sit/connections.json"
}
```

保存后重启 Cursor 或重新加载 MCP。使用时先调用 `mysql_list_connections` 查看连接名，再在查询类工具中传入对应 `connection` 参数。

### 本机有源码时（开发）

在 `mcp-servers/mysql` 目录下：

```bash
cd python_src
pip install -r requirements.txt
```

设置环境变量后：

```bash
python server.py --transport stdio
```

或在项目根目录指定连接文件：

```bash
set MYSQL_CONNECTIONS_FILE=airflow/dags/config/sit/connections.json
python mcp-servers/mysql/python_src/server.py --transport stdio
```

## 安全说明

- 仅支持 **SELECT** 查询，不执行 INSERT/UPDATE/DELETE/DDL。
- 连接文件通常含敏感信息，请勿提交到公开仓库；可放入 `.gitignore` 或使用仅本机配置。