# MySQL MCP Server (mysql-mcp-py)

支持 MySQL 协议的 MCP Server：连接与元数据发现、SQL 分析、安全执行（单条，DDL 不执行，写操作需确认）。

## 环境变量

### 必填（单连接）

| 变量 | 说明 |
|------|------|
| `DB_HOST` | 主机 |
| `DB_USER` | 用户名 |
| `DB_PASSWORD` | 密码 |
| `DB_PORT` | 端口，默认 3306 |
| `DB_DATABASE` | 默认库，可选 |

### 多环境（仅方式二：TEST_DB_PROFILES / UAT_DB_PROFILES / PROD_DB_PROFILES）

- **多环境只配三个变量**：`TEST_DB_PROFILES`、`UAT_DB_PROFILES`、`PROD_DB_PROFILES`，每个为 **JSON 数组** `[{},{}]`，表示该环境下的一条或多条连接。**不需**再配 `DB_HOST`/`DB_USER`/`DB_PASSWORD`。
- 每个数组项需含 `host`、`port`、`user`、`password`；可选 `database`、`description`、`databases`、`name`（子名）。
- Profile 名：`test_0`、`test_1`、`test_finance`（若该项含 `"name":"finance"`）、`uat_0`、`prod_0` 等。默认连接取 prod 下第一个（如 `prod_0`）。
- **单环境**：不设任一 `*_DB_PROFILES` 时，只配 `DB_HOST`、`DB_USER`、`DB_PASSWORD`（及可选 `DB_PORT`、`DB_DATABASE`）。

**示例（test / uat / prod 三环境）**：

```bash
TEST_DB_PROFILES='[{"host":"test-db.example.com","port":3306,"user":"t1","password":"xxx","database":"app_test","description":"测试环境","databases":["app_test"]}]'
UAT_DB_PROFILES='[{"host":"uat-db.example.com","port":3306,"user":"u1","password":"yyy","database":"app_uat","description":"UAT环境","databases":["app_uat"]}]'
PROD_DB_PROFILES='[{"host":"db.example.com","port":3306,"user":"ro","password":"zzz","database":"app","description":"生产环境","databases":["app","report"]}]'
```

测试环境多条连接时，数组里放多项即可，例如：

```bash
TEST_DB_PROFILES='[{"host":"t1","port":3306,"user":"u","password":"p","database":"app"},{"host":"t2","port":3306,"user":"u","password":"p","database":"order","name":"order"}]'
# → profile 为 test_0、test_order
```

调用时传 `connection="test_0"` 或 `connection="prod_0"` 等指定用哪条。

**让智能体根据自然语言选连接**：每项可配 `description`，`list_connections` / `db://config` 会展示，便于将用户说的「测试」「生产」映射到 profile 名。

**每个连接聚焦若干数据库**：每项可配 `databases`：**不配置** → 默认所有库；**空数组 `[]`** → 不允许任何库；**非空数组** → 仅允许这些库。

### 安全与行为

| 变量 | 默认 | 说明 |
|------|------|------|
| `DB_READ_ONLY` | false | 为 true 时仅允许 SELECT |
| `DB_MAX_SELECT_ROWS` | 10000 | SELECT 单次最大行数 |
| `DB_QUERY_TIMEOUT_SECONDS` | 30 | 执行超时(秒) |
| `DB_SLOW_QUERY_SECONDS` | 10 | 超过此秒数提示慢查询 |

## 安装与运行

```bash
# 开发
cd mysql-mcp-py
uv sync
uv run python -m mysql_mcp

# 或安装后
pip install -e .
DB_HOST=localhost DB_USER=root DB_PASSWORD=xxx mysql-mcp-py
```

### Cursor / Claude 配置示例

**发布到 PyPI 后**（用户已 `pip install mysql-mcp-py` 或使用 `uvx`）：

**Cursor** 编辑 `~/.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "database": {
      "command": "uvx",
      "args": ["mysql-mcp-py"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "root",
        "DB_PASSWORD": "your-password",
        "DB_DATABASE": "your_db"
      }
    }
  }
}
```

多环境示例（**只配 TEST_DB_PROFILES / UAT_DB_PROFILES / PROD_DB_PROFILES**，每项需含 `host`、`port`、`user`、`password`）：

```json
{
  "mcpServers": {
    "database": {
      "command": "uvx",
      "args": ["mysql-mcp-py"],
      "env": {
        "TEST_DB_PROFILES": "[{\"host\":\"test-db.example.com\",\"port\":3306,\"user\":\"u\",\"password\":\"p\",\"database\":\"app\"}]",
        "UAT_DB_PROFILES": "[{\"host\":\"uat-db.example.com\",\"port\":3306,\"user\":\"u\",\"password\":\"p\",\"database\":\"app\"}]",
        "PROD_DB_PROFILES": "[{\"host\":\"db.example.com\",\"port\":3306,\"user\":\"ro\",\"password\":\"xxx\",\"database\":\"app\"}]"
      }
    }
  }
}
```

**Claude Desktop** 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）：

```json
{
  "mcpServers": {
    "database": {
      "command": "uvx",
      "args": ["mysql-mcp-py"],
      "env": {
        "DB_HOST": "localhost",
        "DB_USER": "root",
        "DB_PASSWORD": "your-password",
        "DB_DATABASE": "your_db"
      }
    }
  }
}
```

若已用 pip 安装到当前环境，也可直接指定命令（无需 uvx）：

```json
{
  "mcpServers": {
    "database": {
      "command": "mysql-mcp-py",
      "args": [],
      "env": {
        "DB_HOST": "localhost",
        "DB_USER": "root",
        "DB_PASSWORD": "your-password"
      }
    }
  }
}
```

**本地开发**（未发布、从源码运行）：

```json
{
  "mcpServers": {
    "database": {
      "command": "uv",
      "args": ["run", "python", "-m", "mysql_mcp"],
      "cwd": "/path/to/mysql-mcp-py",
      "env": {
        "DB_HOST": "localhost",
        "DB_USER": "root",
        "DB_PASSWORD": "your-password",
        "DB_DATABASE": "your_db"
      }
    }
  }
}
```

## 工具

| 工具 | 说明 |
|------|------|
| `list_connections` | 列出可用连接（profile + 可选说明），便于按用户自然语言选 connection |
| `list_databases` | 列出数据库 |
| `list_tables` | 列出指定库的表 |
| `describe_table` | 表结构（列、行数、大小） |
| `analyze_sql` | 分析 SQL（支持多条），不执行 |
| `execute_sql` | 执行单条 SQL（DDL 不执行，写操作需 confirm=true） |

## 资源

- `db://config` - 配置与安全策略摘要
- `db://databases` - 数据库列表
- `db://tables/{database}` - 表列表
- `db://table/{database}/{table}` - 单表结构

## 提示词

- **`ask_user_which_connection_prompt`** - **连接选择规则**：一开始无已选配置，必须先 list_connections 并让用户选择；用户选择后记住该 connection，后续默认使用且不再提示；仅当用户明确要切换环境时，再次列出并让用户选择
- `query_safely_prompt` - 安全查询习惯
- `explore_schema_prompt` - 先看 Schema 再写 SQL
- `switch_connection_prompt` - 切换环境时带 connection 参数
- `use_connection_from_natural_language_prompt` - 列出配置让用户选择，并根据用户说法映射到 connection

## 设计文档

参见项目内 `docs/plans/2025-03-14-database-mcp-design.md`。

## License

MIT
