内容
# MySQL MCP Tool
一个功能完整的 MySQL MCP (Model Context Protocol) 工具，支持通过 stdio 和 HTTP/SSE 两种传输方式与 AI 助手交互，实现对 MySQL 数据库的查询和管理。
## ✨ 功能特性
- **双模式传输**: 支持 stdio（标准输入输出）和 HTTP/SSE 两种 MCP 传输方式
- **完整的数据库操作**:
- 查询数据 (SELECT)
- 插入数据 (INSERT)
- 更新数据 (UPDATE)
- 删除数据 (DELETE)
- 执行任意 SQL
- 列出所有数据库
- 列出所有表
- 查看表结构 (DESCRIBE)
- 创建/删除表 (DDL)
- **动态数据库切换**: 支持在运行时切换数据库
- **权限控制**: 默认只读模式，可通过配置开启写操作
- **连接池管理**: 使用 MySQL 连接池，支持高并发
## 📦 安装
### 方式一: npm 安装（推荐）
```bash
npm install -g @itkmoon/mysql-mcp
```
客户端配置
```json
{
"mcp": {
"servers": {
"MySQL MCP Tool": {
"command": "npx",
"args": ["-y", "@itkmoon/mysql-mcp"],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASSWORD": "your_password",
"MYSQL_DATABASE": "your_database",
"MYSQL_ALLOW_WRITE": "false"
}
}
}
}
}
```
### 方式二: GitHub 克隆
```bash
git clone https://github.com/ITKMUnigle/MySQL-MCP-Tool.git
cd MySQL-MCP-Tool
npm install
npm run build
```
## ⚙️ 配置
### 环境变量
| 变量 | 说明 | 默认值 |
|------|------|--------|
| `MCP_TRANSPORT` | 传输模式: `stdio` 或 `http` | `stdio` |
| `MCP_HTTP_PORT` | HTTP 端口（仅 http 模式） | `3000` |
| `MYSQL_HOST` | MySQL 地址 | `localhost` |
| `MYSQL_PORT` | MySQL 端口 | `3306` |
| `MYSQL_USER` | 用户名 | `root` |
| `MYSQL_PASSWORD` | 密码 | `root` |
| `MYSQL_DATABASE` | 默认数据库 | - |
| `MYSQL_ALLOW_WRITE` | 启用写操作。支持开启值：`true`、`yes`、`y`；关闭值：`false`、`no`、`n`（大小写不敏感） | `false` |
创建 `.env` 文件：
```env
MCP_TRANSPORT=stdio
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database
MYSQL_ALLOW_WRITE=false
```
## 🚀 使用
### Claude Desktop 配置
```json
{
"mcpServers": {
"MySQL MCP Tool": {
"command": "node",
"args": ["/path/to/node_modules/@itkmoon/mysql-mcp/dist/index.js"],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASSWORD": "your_password",
"MYSQL_DATABASE": "your_database",
"MYSQL_ALLOW_WRITE": "false"
}
}
}
}
```
### Cursor 配置
```json
{
"mcpServers": {
"MySQL MCP Tool": {
"command": "node",
"args": ["/path/to/node_modules/@itkmoon/mysql-mcp/dist/index.js"],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASSWORD": "your_password",
"MYSQL_DATABASE": "your_database",
"MYSQL_ALLOW_WRITE": "false"
}
}
}
}
```
### Trae 配置
```json
{
"mcp": {
"servers": {
"MySQL MCP Tool": {
"command": "node",
"args": ["/path/to/node_modules/@itkmoon/mysql-mcp/dist/index.js"],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASSWORD": "your_password",
"MYSQL_DATABASE": "your_database",
"MYSQL_ALLOW_WRITE": "false"
}
}
}
}
}
```
## 🧪 连接测试
### 用例一：stdio 模式测试
适用于 Claude Desktop、Cursor、Trae 等 AI 客户端，通过标准输入输出与 MCP 服务通信。
**步骤 1：配置环境变量并启动服务**
```bash
# Linux / macOS
export MYSQL_HOST=192.168.1.243
export MYSQL_PORT=3306
export MYSQL_USER=root
export MYSQL_PASSWORD=your_password
export MYSQL_DATABASE=testdb
export MCP_TRANSPORT=stdio
# 启动服务
npx @itkmoon/mysql-mcp --stdio
```
```bash
# Windows (PowerShell)
$env:MYSQL_HOST="192.168.1.243"
$env:MYSQL_PORT="3306"
$env:MYSQL_USER="root"
$env:MYSQL_PASSWORD="your_password"
$env:MYSQL_DATABASE="testdb"
$env:MCP_TRANSPORT="stdio"
# 启动服务
npx @itkmoon/mysql-mcp --stdio
```
**步骤 2：在 AI 客户端中验证**
启动成功后，在 AI 对话框中输入以下指令测试：
```
请帮我：
1. 列出所有数据库（使用 mysql_list_databases）
2. 切换到 testdb 数据库（使用 mysql_use_database）
3. 列出所有表（使用 mysql_list_tables）
4. 查询一张表的前 5 条数据（使用 mysql_query）
```
**预期输出示例：**
```json
// 1. 列出数据库
["information_schema", "mysql", "performance_schema", "sys", "testdb"]
// 2. 切换数据库
{"success": true, "database": "testdb"}
// 3. 列出表
["users", "orders", "products"]
// 4. 查询数据
{
"columns": ["id", "name", "email", "created_at"],
"rows": [
[1, "张三", "zhangsan@example.com", "2026-01-01"],
[2, "李四", "lisi@example.com", "2026-01-02"],
...
],
"rowCount": 5
}
```
---
### 用例二：HTTP/SSE 模式测试
适用于需要远程访问或微服务集成的场景，通过 HTTP 端点与 MCP 服务通信。
**步骤 1：配置环境变量并启动 HTTP 服务**
```bash
# Linux / macOS
export MYSQL_HOST=192.168.1.243
export MYSQL_PORT=3306
export MYSQL_USER=root
export MYSQL_PASSWORD=your_password
export MYSQL_DATABASE=testdb
export MCP_TRANSPORT=http
export MCP_HTTP_PORT=3000
# 启动服务
npx @itkmoon/mysql-mcp --http
```
```bash
# Windows (PowerShell)
$env:MYSQL_HOST="192.168.1.243"
$env:MYSQL_PORT="3306"
$env:MYSQL_USER="root"
$env:MYSQL_PASSWORD="your_password"
$env:MYSQL_DATABASE="testdb"
$env:MCP_TRANSPORT="http"
$env:MCP_HTTP_PORT="3000"
# 启动服务
npx @itkmoon/mysql-mcp --http
```
**启动成功后控制台输出：**
```
MySQL MCP Server running on HTTP port 3000
Health check: http://localhost:3000/health
Tools list: http://localhost:3000/tools
SSE endpoint: http://localhost:3000/sse
```
**步骤 2：验证各端点可用性**
```bash
# 健康检查
curl http://localhost:3000/health
# 预期输出:
# {"status":"healthy","mysql_connected":true,"allow_write":false,"current_database":"testdb"}
# 获取工具列表
curl http://localhost:3000/tools
# 预期输出: 返回所有可用工具的名称和描述列表
```
**步骤 3：测试 SSE 连接**
```bash
# 测试 SSE 长连接
curl -N http://localhost:3000/sse
# 预期输出:
# data: {"type":"connection","status":"connected"}
#
# data: {"type":"ping"}
#
# data: {"type":"ping"}
# ... (每30秒一次心跳)
```
**步骤 4：测试远程访问（局域网内其他设备）**
```bash
# 在局域网内另一台设备上访问（将 192.168.1.10 替换为运行 MCP 服务的机器 IP）
curl http://192.168.1.10:3000/health
# 如果无法访问，请检查：
# 1. 防火墙是否放行 3000 端口
# 2. MySQL 服务器 (.243) 是否允许来自 .10 的连接
```
---
## 🛠️ 可用工具
| 工具 | 说明 |
|------|------|
| `mysql_query` | 执行 SELECT 查询 |
| `mysql_execute` | 执行任意 SQL（需写权限） |
| `mysql_list_databases` | 列出所有数据库 |
| `mysql_list_tables` | 列出数据库中的表 |
| `mysql_describe_table` | 查看表结构 |
| `mysql_use_database` | 切换数据库 |
| `mysql_get_current_database` | 获取当前数据库名 |
| `mysql_get_permissions` | 检查写权限 |
## 🔒 权限控制
默认只读模式，只允许 SELECT 查询。启用写操作：
```env
MYSQL_ALLOW_WRITE=true
```
`MYSQL_ALLOW_WRITE` 支持以下值（大小写不敏感）：
| 值 | 含义 |
|----|------|
| `true` / `yes` / `y` | 启用写操作 |
| `false` / `no` / `n` | 禁用写操作 |
## 📄 许可证
MIT License
## 🔗 链接
- [GitHub](https://github.com/ITKMUnigle/MySQL-MCP-Tool)
- [npm](https://www.npmjs.com/package/@itkmoon/mysql-mcp)
