# mysql_mcp

**Repository Path**: muyi99/mysql_mcp

## Basic Information

- **Project Name**: mysql_mcp
- **Description**: go语言开发的mysql的mcp服务
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: feature/mysql-mcp
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-02
- **Last Updated**: 2026-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mysql-mcp

本地运行的 MySQL MCP Server（Go，stdio 传输）。让 Claude Desktop / Cursor 等 MCP 客户端查询表结构、执行 DDL、增删改查数据——带三档安全防护。

## 功能

- `list_tables` — 列出数据库中的表（支持 LIKE 模式匹配）
- `describe_table` — 查看表结构（列名、类型、索引、注释）
- `read_query` — 执行只读 SQL（SELECT/SHOW/DESCRIBE/EXPLAIN），带行数和 payload 大小上限
- `execute_sql` — 执行写入 SQL（INSERT/UPDATE/DELETE）及 DDL，受安全策略控制

## 三档安全模式

| 安全级别 | 配置 | 允许操作 |
|---------|------|---------|
| `read_only` | 连接属性 `security: read_only` | 仅 SELECT/SHOW/DESCRIBE/EXPLAIN |
| `read_write` | 连接属性 `security: read_write` | + INSERT/UPDATE/DELETE；禁止 DDL |
| `full` | 连接属性 `security: full` | 全部操作；DROP DATABASE 需二次确认 |

写操作（UPDATE/DELETE 无 WHERE、DROP DATABASE 等）需要 `confirm=true` 参数二次确认。

## 快速开始（环境变量模式）

最简单的使用方式——无需配置文件，只需设置环境变量：

```json
{
  "mcpServers": {
    "mysql_fresh": {
      "command": "./mysql-mcp",
      "env": {
        "MYSQL_HOST": "192.168.0.9",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASS": "12341324",
        "MYSQL_DB": "dinghuo_fresh3"
      }
    }
  }
}
```

### 环境变量列表

| 环境变量 | 说明 | 默认值 |
|---|---|---|
| `MYSQL_HOST` | 数据库地址 | `localhost` |
| `MYSQL_PORT` | 端口 | `3306` |
| `MYSQL_USER` | 用户名 | `root` |
| `MYSQL_PASS` | 密码 | (空) |
| `MYSQL_DB` | 数据库名 | (空) |
| `MYSQL_SECURITY` | 安全级别 (`read_only`/`read_write`/`full`) | `read_only` |
| `MYSQL_DEFAULT_MAX_ROWS` | 默认行数限制 | `100` |
| `MYSQL_HARD_MAX_ROWS` | 硬性行数上限 | `1000` |
| `MYSQL_TIMEOUT_SECONDS` | 查询超时(秒) | `30` |

> **提示**：HOST 和 DB 必须同时设置，否则报错。也可以直接设置完整的 `MYSQL_DSN` 跳过所有拼接：
> ```json
> "env": {
>   "MYSQL_DSN": "root:pass@tcp(192.168.0.9:3306)/dinghuo_fresh3?parseTime=true"
> }
> ```

## 安装

```bash
go build -o mysql-mcp ./cmd/mysql-mcp
```

## 配置

创建 `config.yaml`：

```yaml
defaults:
  security: read_only
  query:
    default_max_rows: 100
    hard_max_rows: 1000
    timeout_seconds: 30

connections:
  prod:
    default: true
    dsn_env: MYSQL_DSN
    security: read_write
    deny_patterns: []   # 可选：正则黑名单
  dev:
    dsn: "root@tcp(localhost:3307)/mydb?parseTime=true"
    security: full
```

环境变量覆盖：在连接中设置 `dsn_env: MYSQL_DSN`，运行时 `MYSQL_DSN` 的值会覆盖文件中的 `dsn`。

## 运行

```bash
./mysql-mcp --config config.yaml
```

通过 stdio 与 MCP 客户端通信。日志输出到 stderr，协议数据输出到 stdout。

## MCP 客户端配置

### Claude Desktop

在 MCP 配置中添加：

```json
{
  "mcpServers": {
    "mysql": {
      "command": "./mysql-mcp",
      "args": ["--config", "config.yaml"]
    }
  }
}
```

### Cursor

在 `.cursor/mcp.json` 中添加：

```json
{
  "mcpServers": {
    "mysql": {
      "command": "./mysql-mcp",
      "args": ["--config", "config.yaml"]
    }
  }
}
```

## 项目结构

```
internal/
  config/    多实例 YAML 配置 + 环境变量覆盖
  guard/     SQL 分类器 + Admit 安全裁决（三档模式）
  db/        懒加载连接池（per-instance，cacheTime 强制）
  mysqlmeta/ information_schema 元数据查询
  tools/     MCP 工具处理器（4 个工具）
cmd/mysql-mcp/
  main.go    stdio 入口 + MCP server 接线
  register.go 工具注册
```

## 开发

```bash
# 运行所有测试
go test ./...

# 覆盖率
go test -cover ./...

# 构建
go build ./cmd/mysql-mcp
```