Which integrations are available for this server?

Enables AI assistants to safely query MySQL databases with support for executing SELECT queries, listing tables, viewing table structures, and optional write operations with configurable safety controls.

How do I use MCP MySQL Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP MySQL Server show me the structure of the users table" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP MySQL Server

npm version License: MIT

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

English | 中文

🇨🇳 中文文档

功能特性

✅ 支持 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: 环境变量管理

许可证

MIT License

🇬🇧 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