内容
# @maxlmgc/mysql-mcp
> MySQL MCP 服务器 — 通过模型上下文协议为 AI 客户端提供安全、默认只读的 MySQL 集成。
[中文文档](https://github.com/MaxLMGC/mysql-mcp/blob/main/README_CN.md)
## 工具列表
| 工具 | 描述 | 只读模式 |
|---|---|---|
| `sql_query` | 执行 SELECT / SHOW / DESCRIBE / EXPLAIN 查询 | 允许 |
| `sql_list_tables` | 列出当前数据库中的所有表 | 允许 |
| `sql_table_schema` | 获取表的列结构和注释 | 允许 |
| `sql_execute` | 执行 INSERT / UPDATE / DELETE（自动回滚） | 阻止 |
## 环境变量
### 数据库连接（必填）
| 变量 | 描述 | 默认值 |
|---|---|---|
| `MYSQL_HOST` | 数据库主机 | - |
| `MYSQL_PORT` | 数据库端口 | `3306` |
| `MYSQL_USER` | 数据库用户 | - |
| `MYSQL_PASS` | 数据库密码 | （空） |
| `MYSQL_DB` | 数据库名称 | - |
### 只读模式
| 变量 | 描述 | 默认值 |
|---|---|---|
| `MYSQL_READONLY` | 设置为 `false` 以禁用只读模式 | `true`（启用） |
| `MYSQL_READONLY_PREFIXES` | 自定义 SQL 关键字白名单（逗号分隔，覆盖默认值） | `SELECT,SHOW,DESCRIBE,DESC,EXPLAIN,WITH` |
### 连接池
| 变量 | 描述 | 默认值 |
|---|---|---|
| `MYSQL_CONNECTION_LIMIT` | 连接池中的最大连接数 | `10` |
| `MYSQL_MULTIPLE_STATEMENTS` | 设置为 `false` 以禁用多语句执行 | `true` |
## 安装
```bash
npm install @maxlmgc/mysql-mcp
```
## 用法
### MCP 客户端配置
将以下内容添加到您的 MCP 客户端配置中：
```json
{
"mcpServers": {
"mysql-mcp": {
"command": "npx",
"args": ["-y", "@maxlmgc/mysql-mcp"],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASS": "your_password",
"MYSQL_DB": "your_database"
}
}
}
}
```
### 只读模式（默认）
默认情况下，仅允许查询操作；`sql_execute` 不被公开。
### 禁用只读模式
```json
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_USER": "root",
"MYSQL_DB": "your_database",
"MYSQL_READONLY": "false"
}
```
### 自定义白名单
仅允许 SELECT 和 SHOW：
```json
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_USER": "root",
"MYSQL_DB": "your_database",
"MYSQL_READONLY_PREFIXES": "SELECT,SHOW"
}
```
## 安全性
- **默认只读**：`sql_execute` 在只读模式下不注册
- **防止 SQL 注入**：表名通过正则表达式验证；使用参数化查询
- **启动验证**：缺少必填环境变量会导致立即失败
- **事务回滚**：`sql_execute` 在一个始终回滚的事务中运行
- **双层保护**：在工具层和连接池层进行 SQL 验证
## 许可证
MIT
