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. 配置环境变量

cp .env.example .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 部署

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

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

3. 不使用 Docker 部署

# 安装依赖
npm install

# 构建
npm run build

# 启动
npm start

本地 Claude Code 配置

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

macOS/Linux: ~/.claude/settings.json Windows: %APPDATA%\Claude\claude_desktop_config.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	服务信息

测试连接

# 健康检查
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 只读用户

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

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