# mcp

**Repository Path**: caidingnu/mcp

## Basic Information

- **Project Name**: mcp
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-03
- **Last Updated**: 2026-08-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mcp-mysql-caidingnu

基于 Model Context Protocol (MCP) 的 MySQL 数据库操作服务，支持连接管理、只读查询、数据修改、DDL 操作和表结构探查。

## 环境要求

- Node.js >= 20

## 使用方式

### 方式一：npx 直接运行（推荐，无需安装）

在 MCP 客户端配置中直接使用 `npx`，自动从 npm 拉取并执行：

```json
{
  "mcpServers": {
    "mcp-mysql-caidingnu": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-mysql-caidingnu"],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your-password",
        "MYSQL_DATABASE": "your-database"
      }
    }
  }
}
```

### 方式二：全局安装

```bash
npm install -g mcp-mysql-caidingnu
```

安装后二进制命令 `mcp-mysql-caidingnu` 添加到系统 PATH：

```json
{
  "mcpServers": {
    "mcp-mysql-caidingnu": {
      "type": "stdio",
      "command": "mcp-mysql-caidingnu",
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your-password",
        "MYSQL_DATABASE": "your-database"
      }
    }
  }
}
```

## 各工具配置指南

以上 JSON 配置兼容所有支持 MCP 的客户端：

| 工具 | 配置文件位置 |
|------|-------------|
| **CodeBuddy** | `~/.codebuddy/mcp.json` |
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) 或 `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
| **Cursor** | `.cursor/mcp.json`（项目根目录）或 `~/.cursor/mcp.json` |
| **VS Code / Cline** | 通过 MCP 设置面板添加 |
| **Zed** | `~/.config/zed/mcp.json` 或 `~/.zed/mcp.json` |

## 环境变量（自动连接）

若设置了 `MYSQL_HOST`，启动时会自动建立初始连接，无需手动调用 `mysql_connect`。自动连接的 ID 取 `MYSQL_DATABASE` 的值，若未设置则为 `"default"`。

| 变量 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `MYSQL_HOST` | 否 | — | MySQL 主机地址。不设置则通过 `mysql_connect` 工具手动连接 |
| `MYSQL_PORT` | 否 | `3306` | MySQL 端口 |
| `MYSQL_USER` | 否 | `root` | 用户名 |
| `MYSQL_PASSWORD` | 否 | 空字符串 | 密码 |
| `MYSQL_DATABASE` | 否 | — | 默认数据库 |

## 可用工具

### mysql_connect — 建立 MySQL 连接

动态建立 MySQL 连接池，凭据仅保存在当前 MCP 进程内存中。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `host` | string | 是 | — | MySQL 主机地址 |
| `port` | number | 否 | `3306` | 端口，范围 1 ~ 65535 |
| `user` | string | 是 | — | 用户名 |
| `password` | string | 否 | `""` | 密码 |
| `database` | string | 否 | — | 默认数据库 |
| `label` | string | 否 | `{user}@{host}:{port}` | 自定义连接标签 |
| `ssl` | boolean | 否 | `false` | 是否启用 MySQL TLS 加密连接 |
| `connectTimeoutMs` | number | 否 | `10000` | 连接超时毫秒数，范围 1000 ~ 120000 |

返回 `{ connectionId, host, port, user, database }`。

### mysql_list_connections — 列出所有连接

列出当前 MCP 会话中所有活跃连接，密码不会出现在返回结果中。

无参数。

返回连接列表，每项包含 `connectionId`、`label`、`host`、`port`、`user`、`database`、`createdAt`。

### mysql_disconnect — 关闭连接

关闭指定连接池并从内存中移除。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `connectionId` | string | 是 | `mysql_connect` 返回的连接 ID |

返回 `{ disconnected: true, connectionId }`。

### mysql_query — 执行只读 SQL

仅允许执行 SELECT、SHOW、DESCRIBE、DESC、EXPLAIN 语句，其他 SQL 类型会被拒绝。支持 `?` 参数化占位符。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `connectionId` | string | 是 | — | 连接 ID |
| `sql` | string | 是 | — | 只读 SQL 语句 |
| `parameters` | array | 否 | `[]` | `?` 占位符参数，元素类型为 string / number / boolean / null |

返回 `{ rowCount, columns: string[], rows: object[] }`。

### mysql_execute — 修改数据或表结构

执行 INSERT、UPDATE、DELETE 或 DDL（CREATE / ALTER / DROP / TRUNCATE 等）。DROP 和 TRUNCATE 操作需将 `confirmDestructive` 设为 `true` 才会执行。支持 `?` 参数化占位符。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `connectionId` | string | 是 | — | 连接 ID |
| `sql` | string | 是 | — | 写入或 DDL 语句 |
| `parameters` | array | 否 | `[]` | `?` 占位符参数 |
| `confirmDestructive` | boolean | 否 | `false` | DROP / TRUNCATE 时必须设为 `true` |

返回 `{ affectedRows, changedRows, insertId, warningStatus }`。

### mysql_inspect_schema — 探查数据库结构

通过查询 `information_schema` 获取元数据，按参数组合分三级：

- **无 `database` 无 `table`** → 列出所有数据库（含字符集、排序规则）
- **有 `database` 无 `table`** → 列出该库所有表（含类型、引擎、估算行数、注释）
- **有 `database` 有 `table`** → 返回该表的字段、索引、外键

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `connectionId` | string | 是 | 连接 ID |
| `database` | string | 否 | 目标数据库名。不传则列出所有数据库 |
| `table` | string | 否 | 目标表名。不传则列出指定库的所有表 |

返回根据参数组合分别为 `{ databases }`、`{ database, tables }` 或 `{ database, table, columns, indexes, foreignKeys }`。

## 安全说明

- 连接密码仅保存在 MCP 进程内存中，不写入文件或日志
- `mysql_query` 仅放行 SELECT / SHOW / DESCRIBE / DESC / EXPLAIN 只读语句
- DROP / TRUNCATE 必须显式设置 `confirmDestructive: true`
- 禁用 MySQL 多语句执行（`multipleStatements: false`），单次调用仅执行一条语句
- SQL 参数均通过 `?` 占位符绑定，避免 SQL 注入
- 支持 TLS 加密连接（`mysql_connect` 中 `ssl: true`）
- 建议使用最小权限的 MySQL 账号
- 收到 SIGINT / SIGTERM 时自动关闭所有连接池

## 开发

```bash
npm install        # 安装依赖
npm run dev        # 开发模式（tsx 热加载）
npm run build      # 编译 TypeScript → dist/
npm publish        # 发布（自动执行 build）
```

## License

MIT