# MCP MySQL 查询服务

基于 MCP（Model Context Protocol）协议的 MySQL 只读查询服务。

## 功能特性

- **只读查询**：仅允许 SELECT 操作，确保数据安全
- **双模式运行**：支持 stdio（本地）和 HTTP SSE（远程）
- **三个工具**：query（执行查询）、tables（列表）、schema（表结构）
- **安全防护**：SQL 校验、行数限制、超时控制
- **连接池**：数据库连接池提升性能

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env，根据实际情况修改配置
```

### 3. 运行服务

#### stdio 模式（本地使用）

```bash
python server.py
```

在支持 MCP 的客户端中配置：

```json
{
  "mcpServers": {
    "mysql-query": {
      "command": "python",
      "args": ["path/to/server.py"]
    }
  }
}
```

#### HTTP SSE 模式（远程部署）

```bash
python server.py --http
# 或指定端口
python server.py --http --port 9000
```

服务启动后，访问 `http://localhost:8000/sse` 建立 SSE 连接。

## 工具说明

### query - 执行 SQL 查询

执行 SELECT SQL 语句，返回查询结果。

**参数：**
- `sql` (string, 必填)：要执行的 SELECT SQL 语句

**示例：**
```
SELECT * FROM users LIMIT 10
```

### tables - 列出所有表

列出当前数据库中的所有表及其注释。

### schema - 查看表结构

查看指定表的字段结构。

**参数：**
- `table_name` (string, 必填)：表名

## 安全限制

- 只允许 SELECT 查询
- 禁止 INSERT / UPDATE / DELETE / DROP 等写操作
- 单次查询最多返回 1000 行
- 查询超时 30 秒
- 禁止执行多条 SQL 语句

## 配置项

| 环境变量 | 默认值 | 说明 |
|---------|-------|------|
| MYSQL_HOST | localhost | 数据库地址 |
| MYSQL_PORT | 3306 | 数据库端口 |
| MYSQL_USER | mysqltest | 数据库用户名 |
| MYSQL_PASSWORD | 123456 | 数据库密码 |
| MYSQL_DATABASE | cptest | 数据库名 |
| MAX_ROWS | 1000 | 最大返回行数 |
| QUERY_TIMEOUT | 30 | 查询超时（秒） |
| POOL_SIZE | 5 | 连接池大小 |
| MCP_MODE | stdio | 运行模式（stdio/http） |
| HTTP_PORT | 8000 | HTTP 端口 |

## 目录结构

```
mcp-mysql/
├── server.py              # 服务入口
├── config.py              # 配置管理
├── db/
│   ├── __init__.py
│   ├── connection.py      # 连接池管理
│   └── queries.py         # 查询执行 + 安全校验
├── tools/
│   ├── __init__.py        # 工具注册
│   ├── query.py           # query 工具
│   ├── tables.py          # tables 工具
│   └── schema.py          # schema 工具
├── requirements.txt       # 依赖清单
├── .env.example           # 环境变量模板
└── README.md              # 使用说明
```