# mysql_mcp_server

**Repository Path**: L_934586/mysql_mcp_server

## Basic Information

- **Project Name**: mysql_mcp_server
- **Description**: mysql的mcp本地服务
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-11
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MySQL MCP Server

通过 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 让 Claude Code 能够安全地**只读访问** MySQL 数据库——查询表结构、浏览数据、执行只读 SQL。

## 功能

| 工具 | 说明 |
|---|---|
| `list_connections` | 列出所有已配置的 MySQL 连接（不暴露密码） |
| `list_databases` | 查看指定连接可见的数据库列表 |
| `list_tables` | 查看指定数据库中的所有表 |
| `get_schema_info` | 获取表的列名、数据类型、主键、注释等元数据 |
| `get_table_sample` | 采样查看表数据（默认 5 行，最多 20 行） |
| `query_readonly` | 执行只读 SQL（仅允许 SELECT / SHOW / DESCRIBE / DESC / EXPLAIN / WITH） |

此外还暴露了 MCP Resources（`mysql://{connection}/{database}/tables`、`mysql://{connection}/{database}/table/{table_name}/schema` 等）和一个 `explore_database` 探索提示词。

## 安全特性

- 内置 SQL 语句检查：拒绝 `INSERT` / `UPDATE` / `DELETE` / `DROP` 等写操作
- 拒绝多语句 SQL，防止 SQL 注入
- 表名和连接名经过严格校验（仅允许字母、数字、下划线和 `$`）
- 密码通过环境变量传入，不落盘
- 建议使用专门的只读数据库用户

## 前置条件

- Python >= 3.11
- 一个 MySQL 实例（本地或远程）
- Claude Code CLI

## 快速开始

### 1. 创建只读 MySQL 用户

```sql
CREATE USER 'mcp_ro'@'127.0.0.1' IDENTIFIED BY 'your_password';
GRANT SELECT, SHOW VIEW ON your_database.* TO 'mcp_ro'@'127.0.0.1';
FLUSH PRIVILEGES;
```

### 2. 安装

```bat
cd C:\Users\weijunliu\Desktop\mysql_mcp_server
python -m venv .venv
.venv\Scripts\activate
python -m pip install -e .
```

安装完成后，`mysql-mcp-minimal` 命令即可在虚拟环境中使用。

### 3. 配置

支持三种配置方式，按优先级从低到高：

#### 方式 A：单连接——通过 MCP 环境变量（最简单）

直接在注册 MCP 服务器时传入连接信息：

```bat
claude mcp add --transport stdio mysql-local ^
  --env MYSQL_HOST=127.0.0.1 ^
  --env MYSQL_PORT=3306 ^
  --env MYSQL_USER=mcp_ro ^
  --env MYSQL_PASSWORD=your_password ^
  --env MYSQL_DATABASE=your_database ^
  -- .venv\Scripts\mysql-mcp-minimal.exe
```

> 这种方式下服务器自动使用上述环境变量连接，无需额外配置文件。

#### 方式 B：多连接——通过 `connections.json` 文件

在 `mysql_mcp_server.py` 同级目录下创建 `connections.json`：

```json
{
  "local": {
    "host": "127.0.0.1",
    "port": 3306,
    "user": "mcp_ro",
    "password_env": "MYSQL_LOCAL_PASSWORD",
    "database": "your_database",
    "connection_timeout": 10
  },
  "staging": {
    "host": "192.168.1.100",
    "port": 3306,
    "user": "mcp_ro",
    "password_env": "MYSQL_STAGING_PASSWORD",
    "database": "staging_db",
    "connection_timeout": 15
  }
}
```

密码分别通过 `MYSQL_LOCAL_PASSWORD` 和 `MYSQL_STAGING_PASSWORD` 环境变量提供。

#### 方式 C：多连接——通过 `MYSQL_CONNECTIONS` 环境变量

设置 `MYSQL_CONNECTIONS=local,staging`，然后为每个连接定义独立的环境变量：

| 环境变量 | 说明 | 必填 |
|---|---|---|
| `MYSQL_{NAME}_HOST` | 主机地址，默认 127.0.0.1 | 否 |
| `MYSQL_{NAME}_PORT` | 端口，默认 3306 | 否 |
| `MYSQL_{NAME}_USER` | 用户名 | 是 |
| `MYSQL_{NAME}_PASSWORD` | 密码 | 是 |
| `MYSQL_{NAME}_DATABASE` | 默认数据库 | 否 |
| `MYSQL_{NAME}_ENABLED` | 是否启用（0/false 禁用） | 否 |
| `MYSQL_{NAME}_CONNECT_TIMEOUT` | 连接超时秒数，默认 10 | 否 |
| `MYSQL_{NAME}_CHARSET` | 字符集，如 utf8mb4 | 否 |
| `MYSQL_{NAME}_COLLATION` | 排序规则 | 否 |
| `MYSQL_{NAME}_SSL_CA` | SSL CA 证书路径 | 否 |
| `MYSQL_{NAME}_SSL_CERT` | SSL 客户端证书路径 | 否 |
| `MYSQL_{NAME}_SSL_KEY` | SSL 客户端密钥路径 | 否 |
| `MYSQL_{NAME}_SSL_VERIFY_CERT` | 是否验证服务器证书 | 否 |
| `MYSQL_{NAME}_SSL_VERIFY_IDENTITY` | 是否验证证书身份 | 否 |

也可以设置 `MYSQL_CONNECTIONS_FILE` 环境变量指定 `connections.json` 的自定义路径。

### 4. 注册到 Claude Code

```bat
claude mcp add --transport stdio mysql-local ^
  --env MYSQL_CONNECTIONS=local ^
  --env MYSQL_LOCAL_USER=mcp_ro ^
  --env MYSQL_LOCAL_PASSWORD=your_password ^
  --env MYSQL_LOCAL_DATABASE=your_database ^
  -- .venv\Scripts\mysql-mcp-minimal.exe
```

验证注册结果：

```bat
claude mcp list
```

### 5. 在 Claude Code 中使用

在对话中直接提问：

```
用 mysql-local 连接查看有哪些数据库，列出第一个数据库的所有表，并总结表结构。
```

或者查看可用的 MCP 工具：

```
/mcp
```

## 开发

```bat
.venv\Scripts\activate
python mysql_mcp_server.py
```

服务器以 stdio 模式运行，等待 MCP 客户端连接。

## 项目结构

```
mysql_mcp_server/
├── mysql_mcp_server.py    # 主服务器代码
├── connections.json       # 多连接配置（可选，不提交到 git）
├── pyproject.toml         # Python 包配置
└── README.md
```

## 注意事项

- `query_readonly` 拒绝写操作和多语句 SQL
- 表名通过参数化查询和安全校验防止 SQL 注入
- 连接密码始终通过环境变量传入，不会明文存储在配置文件中
- 如需扩展写操作，建议作为独立的 MCP 服务器并配合 Claude Code 的审批机制使用