# MySQL MCP Proxy

一个基于 MCP (Model Context Protocol) 的 MySQL 数据库代理服务，支持通过 HTTP 远程访问数据库。

## 功能特性

- ✅ **Streamable HTTP 传输** - 使用 MCP 最新标准协议
- ✅ **API Key 认证** - Bearer Token 认证机制
- ✅ **只读安全** - 仅允许 SELECT/SHOW/DESCRIBE/EXPLAIN 查询
- ✅ **Docker 部署** - 支持 Docker Compose 一键部署
- ✅ **健康检查** - 内置健康检查端点

## 提供的 MCP 工具

| 工具名 | 描述 |
|--------|------|
| `query` | 执行只读 SQL 查询（SELECT/SHOW/DESCRIBE/EXPLAIN） |
| `list_tables` | 列出当前数据库中的所有表 |
| `describe_table` | 查看指定表的结构 |
| `show_create_table` | 显示创建表的 SQL 语句 |

## 快速开始

### 1. 配置环境变量

```bash
cp .env.example .env
```

编辑 `.env` 文件：

```env
# MySQL 配置
MYSQL_HOST=your-mysql-host
MYSQL_PORT=3306
MYSQL_USER=your-readonly-user
MYSQL_PASSWORD=your-password
MYSQL_DATABASE=your-database

# API Key（生成一个强随机字符串）
API_KEY=your-secure-api-key-here

# 服务端口
PORT=3000
```

### 2. 使用 Docker Compose 部署

```bash
# 构建并启动
docker-compose up -d --build

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

### 3. 不使用 Docker 部署

```bash
# 安装依赖
npm install

# 构建
npm run build

# 启动
npm start
```

## 本地 Claude Code 配置

在你的 Claude Code 配置文件中添加远程 MCP 服务器：

**macOS/Linux**: `~/.claude/settings.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "remote-mysql": {
      "command": "npx",
      "args": ["-y", "@pyroprompts/mcp-stdio-to-streamable-http-adapter"],
      "env": {
        "URI": "https://your-server.com/mcp",
        "MCP_NAME": "remote-mysql",
        "BEARER_TOKEN": "your-api-key-here"
      }
    }
  }
}
```

## API 端点

| 端点 | 方法 | 描述 |
|------|------|------|
| `/mcp` | POST | MCP 消息端点 |
| `/mcp` | GET | SSE 流（需要 session ID） |
| `/mcp` | DELETE | 关闭会话 |
| `/health` | GET | 健康检查 |
| `/` | GET | 服务信息 |

## 测试连接

```bash
# 健康检查
curl http://localhost:3000/health

# MCP 初始化测试
curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    }
  }'
```

## 安全建议

1. **使用 HTTPS** - 在生产环境中，使用 Nginx 反向代理配置 SSL 证书
2. **强 API Key** - 使用至少 32 字符的随机字符串
3. **数据库只读账户** - 为此服务创建专门的只读数据库用户
4. **IP 白名单** - 在防火墙层面限制访问 IP

### 创建 MySQL 只读用户

```sql
CREATE USER 'mcp_readonly'@'%' IDENTIFIED BY 'your-secure-password';
GRANT SELECT, SHOW VIEW ON your_database.* TO 'mcp_readonly'@'%';
FLUSH PRIVILEGES;
```

### Nginx 反向代理配置示例

```nginx
server {
    listen 443 ssl;
    server_name your-server.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location /mcp {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

## 项目结构

```
mcp-mysql-proxy/
├── src/
│   ├── index.ts          # MCP HTTP 服务器入口
│   ├── mysql-tools.ts    # MySQL MCP 工具定义
│   └── auth.ts           # API Key 认证中间件
├── package.json
├── tsconfig.json
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md
```

## License

MIT