# MySQL MCP Server

> 让AI安全地理解和操作你的MySQL/MariaDB数据库

[![MCP](https://img.shields.io/badge/MCP-1.27-blue)](https://modelcontextprotocol.io)
[![Python](https://img.shields.io/badge/Python-3.10+-green)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)

## ✨ 特性

- 🔒 **安全优先** — 默认只读模式，写操作需显式开启
- 📊 **智能分析** — 表结构、统计信息、执行计划一键获取
- 🇨🇳 **中文优先** — 文档、错误提示、注释全部中文化
- 🔌 **即插即用** — 支持Claude Desktop、Cursor、Cline等MCP客户端
- 🛡️ **访问控制** — 可配置允许的数据库和禁止的表
- 🔄 **连接池** — 自动管理数据库连接，高效复用

## 🚀 快速开始

### 安装

```bash
pip install mysql-mcp-server
```

### 配置

在Claude Desktop的配置文件中添加：

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "mysql": {
      "command": "python",
      "args": ["-m", "mysql_mcp_server"],
      "env": {
        "MYSQL_MCP_HOST": "localhost",
        "MYSQL_MCP_PORT": "3306",
        "MYSQL_MCP_USER": "root",
        "MYSQL_MCP_PASSWORD": "your_password",
        "MYSQL_MCP_DATABASE": "your_database",
        "MYSQL_MCP_READ_ONLY": "true"
      }
    }
  }
}
```

### Cursor配置

在Cursor的MCP设置中添加：

```json
{
  "mcpServers": {
    "mysql": {
      "command": "python",
      "args": ["-m", "mysql_mcp_server"],
      "env": {
        "MYSQL_MCP_HOST": "localhost",
        "MYSQL_MCP_PORT": "3306",
        "MYSQL_MCP_USER": "root",
        "MYSQL_MCP_PASSWORD": "your_password",
        "MYSQL_MCP_DATABASE": "your_database"
      }
    }
  }
}
```

## 🛠️ 工具列表

| 工具 | 说明 | 安全级别 |
|------|------|---------|
| `list_databases` | 列出所有可访问的数据库 | 🟢 只读 |
| `list_tables` | 列出指定数据库的所有表 | 🟢 只读 |
| `describe_table` | 获取表的详细结构（列、索引、建表语句） | 🟢 只读 |
| `query` | 执行SQL查询（仅SELECT/SHOW/DESCRIBE） | 🟢 只读 |
| `get_table_sample` | 获取表的样本数据 | 🟢 只读 |
| `get_table_stats` | 获取表的统计信息（行数、大小等） | 🟢 只读 |
| `explain_query` | 获取SQL执行计划 | 🟢 只读 |
| `execute_write` | 执行写操作（INSERT/UPDATE/DELETE） | 🔴 需关闭只读 |

## ⚙️ 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `MYSQL_MCP_HOST` | localhost | MySQL主机地址 |
| `MYSQL_MCP_PORT` | 3306 | MySQL端口 |
| `MYSQL_MCP_USER` | root | MySQL用户名 |
| `MYSQL_MCP_PASSWORD` | (空) | MySQL密码 |
| `MYSQL_MCP_DATABASE` | (空) | 默认数据库 |
| `MYSQL_MCP_READ_ONLY` | true | 只读模式 |
| `MYSQL_MCP_MAX_ROWS` | 100 | 查询结果最大行数 |
| `MYSQL_MCP_QUERY_TIMEOUT` | 30 | 查询超时（秒） |
| `MYSQL_MCP_ALLOWED_DATABASES` | (空=全部) | 允许访问的数据库列表 |
| `MYSQL_MCP_BLOCKED_TABLES` | (空=无) | 禁止访问的表列表 |

## 🔒 安全说明

1. **默认只读** — 服务器启动后默认为只读模式，只能执行SELECT等查询
2. **写操作需显式开启** — 设置 `MYSQL_MCP_READ_ONLY=false` 才能使用 `execute_write`
3. **访问控制** — 可通过 `ALLOWED_DATABASES` 限制可访问的数据库
4. **表级屏蔽** — 可通过 `BLOCKED_TABLES` 屏蔽敏感表（支持通配符）
5. **结果限制** — 默认最多返回100行，防止意外返回大量数据
6. **超时保护** — 查询默认30秒超时，防止长时间运行的查询

## 📝 使用示例

### 在Claude中对话

```
你: 帮我看看数据库里有哪些表
Claude: [调用 list_databases → list_tables] 你的数据库中有以下表...

你: users表的结构是什么？
Claude: [调用 describe_table] users表有以下字段...

你: 帮我查一下最近注册的10个用户
Claude: [调用 query] SELECT * FROM users ORDER BY created_at DESC LIMIT 10

你: 这个查询为什么这么慢？
Claude: [调用 explain_query] 让我看看执行计划...
```

## 🏗️ 开发

```bash
# 克隆仓库
git clone https://github.com/your-username/mysql-mcp-server.git

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest tests/
```

## 📄 License

MIT License