MCP MySQL Server
Model Context Protocol (MCP) server for MySQL - 让 AI 助手（Cursor、Claude Desktop）能够安全地查询 MySQL 数据库。
🇨🇳 中文文档
功能特性
- ✅ 支持 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