# MySQL MCP Server

> **AI-to-DB Secure Gateway** — 不只是一个 MCP Server，而是 AI 与数据库之间的安全执行网关。

基于 **NestJS + TypeScript** 构建，通过 MCP 协议为 Claude Code 等 AI 助手提供对 MySQL 数据库的受控访问能力。核心目标是在 AI 的灵活性与数据库的安全性之间建立可信边界。

---

## 设计理念

传统数据库工具直接暴露执行能力，对 AI 调用者而言风险极高。本项目的核心设计原则：

- **最小权限**：工具按风险分级，高危操作默认关闭
- **AST 级校验**：不依赖关键字匹配，通过 SQL Parser 解析语法树做严格校验
- **可审计**：每次操作完整记录，行为可追溯
- **可控执行**：AI 可以分析（EXPLAIN）但不能随意破坏

---

## 快速开始

```bash
npm install
cp .env.example .env
# 编辑 .env 填入 MySQL 连接信息

npm run start:dev   # 开发模式
npm run build       # 构建
npm run start:prod  # 生产运行
```

### 在 Claude Code 中配置

先构建项目：

```bash
npm run build
```

使用 `claude mcp add` 命令注册（推荐，写入用户级全局配置）：

```bash
claude mcp add mysql node /path/to/mysql-mcp-nest/dist/main.js \
  --scope user \
  -e DB_HOST=127.0.0.1 \
  -e DB_PORT=3306 \
  -e DB_USER=root \
  -e DB_PASSWORD=your_password \
  -e DB_DATABASE=your_database \
  -e PERMISSION_MODE=read_write \
  -e AUDIT_LOG_ENABLED=true \
  -e AUDIT_LOG_DIR=/path/to/mysql-mcp-nest/logs
```

- `--scope user`：写入 `~/.claude.json`，所有项目均可使用
- `--scope project`：写入当前项目的 `.claude.json`，仅当前项目可用

注册后重启 `claude`，执行 `/mcp` 验证连接状态：

```
❯ /mcp
  mysql  connected
```

### 在 Codex 中配置

先构建项目：

```bash
npm run build
```

使用 `codex mcp add` 命令注册到 Codex：

```bash
codex mcp add mysql \
  --env DB_HOST=127.0.0.1 \
  --env DB_PORT=3306 \
  --env DB_USER=root \
  --env DB_PASSWORD=your_password \
  --env DB_DATABASE=your_database \
  --env PERMISSION_MODE=read_write \
  --env AUDIT_LOG_ENABLED=true \
  --env AUDIT_LOG_DIR=/path/to/mysql-mcp-nest/logs \
  -- node /path/to/mysql-mcp-nest/dist/main.js
```

验证配置是否写入成功：

```bash
codex mcp list
codex mcp get mysql
```

注册后重启 Codex，或重新开启一个 Codex 会话，让 MCP 配置生效。

连接成功后即可直接使用：

```
列出 your_database 中的所有表
```

### 在 Cursor 中配置

项目已包含 `.cursor/mcp.json`，Cursor 打开本仓库后会注册 `mysql` MCP Server：

```json
{
  "mcpServers": {
    "mysql": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/main.js"],
      "envFile": "${workspaceFolder}/.env",
      "env": {
        "AUDIT_LOG_DIR": "${workspaceFolder}/logs"
      }
    }
  }
}
```

使用前先构建项目，并确认 `.env` 里已填好 MySQL 连接信息：

```bash
npm run build
```

然后重启 Cursor，或在 Cursor Settings → MCP 中刷新/启用 `mysql`。