MCP MySQL Server

Model Context Protocol (MCP) server for MySQL - 让 AI 助手（Cursor、Claude Desktop）能够安全地查询 MySQL 数据库。

English | 中文

---

<a name="chinese"></a>🇨🇳 中文文档

功能特性

• ✅ 支持 SQL 查询（SELECT、SHOW、DESCRIBE）
• ✅ 列出数据库所有表
• ✅ 查看表结构
• ✅ 安全检查（禁止 DDL 操作）
• ✅ 可选的写操作控制
• ✅ 连接池管理
• ✅ 环境变量配置

快速开始

方法 1：通过 npm 全局安装（推荐）

# 全局安装
npm install -g @shuwu/mcp-mysql-server

# 或使用 npx（无需安装）
npx @shuwu/mcp-mysql-server

方法 2：本地开发安装

# 克隆或下载项目
git clone https://github.com/your-username/mcp-mysql-server.git
cd mcp-mysql-server

# 安装依赖
npm install

配置数据库

创建 .env 文件：

DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=your_database
ALLOW_WRITE=false

测试运行

npm start

看到以下输出表示成功：

[MCP MySQL] 连接池已创建: localhost:3306/your_database
[MCP MySQL] 数据库连接成功 ✓
[MCP MySQL] 服务器已启动，等待请求...
[MCP MySQL] 写操作: 禁止

配置 Cursor AI

方法 1：使用全局安装的包（推荐）

如果你通过 npm install -g 全局安装了包，配置更简单：

Windows 配置：

编辑配置文件：%APPDATA%\Cursor\User\globalStorage\settings.json

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["@shuwu/mcp-mysql-server"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "root",
        "DB_PASSWORD": "your_password",
        "DB_NAME": "your_database",
        "ALLOW_WRITE": "false"
      }
    }
  }
}

macOS/Linux 配置：

编辑配置文件：~/.config/Cursor/User/globalStorage/settings.json

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["@shuwu/mcp-mysql-server"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "root",
        "DB_PASSWORD": "your_password",
        "DB_NAME": "your_database",
        "ALLOW_WRITE": "false"
      }
    }
  }
}

方法 2：使用本地项目路径

如果你是本地开发安装，需要指定完整路径：

Windows 配置：

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["C:\\path\\to\\mcp-mysql-server\\index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "root",
        "DB_PASSWORD": "your_password",
        "DB_NAME": "your_database"
      }
    }
  }
}

macOS/Linux 配置：

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": ["/path/to/mcp-mysql-server/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_USER": "root",
        "DB_PASSWORD": "your_password",
        "DB_NAME": "your_database"
      }
    }
  }
}

重启 Cursor

配置完成后，重启 Cursor 使配置生效。

使用示例

配置完成后，在 Cursor 中可以直接询问 AI：

# 查询用户表
查询 sys_user 表的前 10 条数据

# 列出所有表
数据库有哪些表？

# 查看表结构
ai_character 表的结构是什么？

# 复杂查询
查询最近 7 天创建的角色，并按创建时间倒序排列

AI 助手会自动调用 MCP 服务查询数据库并返回结果。

可用工具

MCP 服务器提供以下工具：

1. query - 执行 SQL 查询

{
  "name": "query",
  "arguments": {
    "sql": "SELECT * FROM sys_user LIMIT 10"
  }
}

2. list_tables - 列出所有表

{
  "name": "list_tables"
}

3. describe_table - 查看表结构

{
  "name": "describe_table",
  "arguments": {
    "table": "ai_character"
  }
}

安全说明

默认安全策略

• ✅ 允许：SELECT、SHOW、DESCRIBE（只读查询）
• ❌ 禁止：INSERT、UPDATE、DELETE（需手动开启）
• ❌ 禁止：CREATE、DROP、ALTER、TRUNCATE（DDL 操作）

开启写操作

如需允许 AI 执行写操作（谨慎使用），修改 .env：

ALLOW_WRITE=true

推荐：创建只读用户

建议为 MCP 服务创建专用的只读数据库用户：

-- 创建只读用户
CREATE USER 'shuwu_readonly'@'localhost' IDENTIFIED BY 'your_password';

-- 授予只读权限
GRANT SELECT ON shuwu.* TO 'shuwu_readonly'@'localhost';

-- 刷新权限
FLUSH PRIVILEGES;

然后修改 .env：

DB_USER=shuwu_readonly
DB_PASSWORD=your_password

故障排查

1. 连接失败

检查：

• MySQL 是否正在运行：mysql -u root -p
• .env 中的用户名密码是否正确
• 防火墙是否阻止连接

2. Cursor 无法识别

检查：

• 配置文件路径是否正确（使用绝对路径）
• Windows 路径使用双反斜杠 \\
• 是否重启了 Cursor

3. 权限错误

检查：

• 数据库用户是否有足够权限
• 是否需要开启 ALLOW_WRITE

开发模式

使用自动重载（修改代码自动重启）：

npm run dev

技术栈

• Node.js: 22+
• @modelcontextprotocol/sdk: MCP 协议实现
• mysql2: MySQL 数据库驱动
• dotenv: 环境变量管理

相关链接

• Model Context Protocol 官方文档
• MCP SDK GitHub
• MySQL2 文档

许可证

MIT License

---

<a name="english"></a>🇬🇧 English Documentation

Features

• ✅ Support SQL queries (SELECT, SHOW, DESCRIBE)
• ✅ List all database tables
• ✅ View table structure
• ✅ Safety checks (prohibit DDL operations)
• ✅ Optional write operation control
• ✅ Connection pool management
• ✅ Environment variable configuration

Quick Start

Method 1: Install via npm (Recommended)

# Global installation
npm install -g @shuwu/mcp-mysql-server

# Or use npx (no installation needed)
npx @shuwu/mcp-mysql-server

Method 2: Local Development

git clone https://github.com/your-username/mcp-mysql-server.git
cd mcp-mysql-server
npm install

Database Configuration

Create a .env file:

DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=your_database
ALLOW_WRITE=false

Configure Cursor AI

Edit configuration file and add:

Windows: %APPDATA%\Cursor\User\globalStorage\settings.json
macOS/Linux: ~/.config/Cursor/User/globalStorage/settings.json

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["@shuwu/mcp-mysql-server"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "root",
        "DB_PASSWORD": "your_password",
        "DB_NAME": "your_database",
        "ALLOW_WRITE": "false"
      }
    }
  }
}

Restart Cursor after configuration.

Usage Examples

After configuration, you can ask AI directly in Cursor:

# Query user table
Show me the first 10 rows from sys_user table

# List all tables
What tables are in the database?

# View table structure
What's the structure of the users table?

# Complex query
Find all active users created in the last 7 days

---

Powered by Model Context Protocol
Built with ❤️ by shuwu Team