# MySQL MCP Server

基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的 MySQL 数据库访问服务，供大模型通过标准化的工具接口对 MySQL 执行查询、增删改、表结构查看等操作。

## 特性

- **4 个 MCP 工具**：`mysql_query` / `mysql_execute` / `mysql_list` / `mysql_describe`
- **Streamable HTTP 传输**：基于 HTTP 的流式传输，适合远程调用场景
- **参数化查询**：使用 `?` 占位符绑定参数，防止 SQL 注入
- **连接池**：mysql2 连接池复用连接，支持并发
- **只读模式开关**：开启后仅允许读操作，防止误删数据
- **凭据环境变量化**：所有敏感信息通过 `.env` 注入，不硬编码

## 技术栈

- TypeScript + Node.js 18+
- `@modelcontextprotocol/sdk`（官方 MCP SDK）
- `mysql2`（纯 JS MySQL 驱动，支持 Promise）
- `zod`（参数校验）

## 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 配置环境变量

复制示例配置文件并填写你的 MySQL 连接信息：

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

编辑 `.env`：

```env
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database

MYSQL_POOL_SIZE=10
MYSQL_READ_ONLY=false

MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=3000
```

### 3. 编译

```bash
npm run build
```

### 4. 启动服务

```bash
npm start
```

服务启动后监听 `http://127.0.0.1:3000/mcp`，MCP 端点为 `/mcp`（支持 POST / GET / DELETE）。

开发模式（监听文件变化自动编译）：

```bash
npm run dev
```

## 工具说明

| 工具 | 用途 | 入参 | 只读模式 |
|------|------|------|---------|
| `mysql_query` | 执行返回结果集的语句（SELECT） | `sql`, `params?`, `database?` | 仅允许 SELECT/SHOW/DESCRIBE/EXPLAIN |
| `mysql_execute` | 执行 DDL（CREATE/ALTER/DROP）和 DML（INSERT/UPDATE/DELETE） | `sql`, `params?`, `database?` | 完全禁用 |
| `mysql_list` | 列出所有数据库或指定库的表 | `type: "databases"\|"tables"`, `database?` | 允许 |
| `mysql_describe` | 查看表的列定义 | `table`, `database?` | 允许 |

### 使用示例

**查询数据：**

```json
{
  "sql": "SELECT id, name, email FROM users WHERE age > ? ORDER BY id LIMIT ?",
  "params": [18, 10]
}
```

**插入数据：**

```json
{
  "sql": "INSERT INTO users (name, email) VALUES (?, ?)",
  "params": ["Alice", "alice@example.com"]
}
```

**列出数据库：**

```json
{ "type": "databases" }
```

**查看表结构：**

```json
{ "table": "users" }
```

## 安全设计

- **凭据管理**：所有 MySQL 连接信息通过环境变量注入，`.env` 已加入 `.gitignore`
- **SQL 注入防护**：所有用户输入通过 mysql2 的 `?` 占位符参数绑定，表名等标识符通过白名单校验
- **只读模式**：`MYSQL_READ_ONLY=true` 时，`mysql_query` 仅允许 SELECT 类语句，`mysql_execute` 完全禁用
- **连接池限制**：通过 `MYSQL_POOL_SIZE` 限制最大连接数，防止资源泄露
- **错误信息**：MySQL 错误返回结构化信息（errno、sqlMessage），不暴露凭据

## MCP Client 对接

### 在 Claude Desktop / Cursor 等客户端中配置

由于本服务使用 Streamable HTTP 传输，在 MCP Client 配置中添加：

```json
{
  "mcpServers": {
    "mysql": {
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}
```

## 项目结构

```
├── package.json
├── tsconfig.json
├── .env.example
├── .gitignore
├── README.md
└── src/
    ├── index.ts              # 入口：HTTP 服务 + MCP Server
    ├── config.ts             # 环境变量读取与校验
    ├── db.ts                 # mysql2 连接池封装
    ├── guard.ts              # 只读模式守卫
    └── tools/
        ├── index.ts          # 工具注册总入口
        ├── query.ts          # mysql_query
        ├── execute.ts        # mysql_execute
        ├── list.ts           # mysql_list
        └── describe.ts       # mysql_describe
```

## License

MIT