MySQL MCP Server

一个功能完整的 MySQL Model Context Protocol (MCP) 服务器提供数据库管理功能

功能特性

• 数据库管理创建删除列出数据库
• 表管理创建删除列出描述表结构
• CRUD 操作查询插入更新删除数据
• SQL 执行执行任意 SQL 语句
• 连接管理测试连接切换数据库
• Schema 查询获取完整的数据库结构信息支持自然语言转 SQL

安装

前置要求

• Node.js 18+
• MySQL 服务器已安装并运行

net start mysql80

安装步骤

1. 克隆仓库

git clone https://github.com/blackdesert5410/mysql-mcp-server.git
cd mysql-mcp-server

1. 安装依赖

npm install

配置

方式一命令行参数推荐

启动时通过命令行参数传递 MySQL 用户名和密码

node src/index.js <用户名> <密码>

示例

node src/index.js root your_password

方式二环境变量

1. 复制示例配置文件

cp config.example.env .env

1. 编辑 .env 文件填入你的 MySQL 配置

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=your_username
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=

1. 启动服务器无需命令行参数

node src/index.js

优先级命令行参数 > 环境变量 > 默认值

使用方法

启动服务器

# 使用命令行参数
node src/index.js <用户名> <密码>

# 或使用 npm start需要先配置环境变量
npm start

在 Cursor 中配置

1. 打开 Cursor 的 MCP 配置文件通常在 ~/.cursor/mcp.json 或 %APPDATA%\Cursor\mcp.json

2. 添加以下配置

Windows 路径格式推荐使用正斜杠

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": [
        "D:/AI/mcp-server/src/index.js",
        "your_username",
        "your_password"
      ]
    }
  }
}

或者使用双反斜杠

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": [
        "D:\\AI\\mcp-server\\src\\index.js",
        "your_username",
        "your_password"
      ]
    }
  }
}

如果 Node.js 不在 PATH 中使用完整路径

{
  "mcpServers": {
    "mysql": {
      "command": "C:/Program Files/nodejs/node.exe",
      "args": [
        "D:/AI/mcp-server/src/index.js",
        "your_username",
        "your_password"
      ]
    }
  }
}

注意

• 将路径替换为你的实际项目路径
• 将 your_username 和 your_password 替换为你的 MySQL 用户名和密码
• Windows 路径使用正斜杠 / 或双反斜杠 \\
• 修改配置后需要重启 Cursor 才能生效

在其他 MCP 客户端中使用

{
  "mcpServers": {
    "mysql": {
      "command": "node",
      "args": [
        "/path/to/mysql-mcp-server/src/index.js",
        "your_username",
        "your_password"
      ]
    }
  }
}

可用工具

数据库管理

1. test_connection - 测试 MySQL 连接
2. list_databases - 列出所有数据库
3. create_database - 创建新数据库
4. drop_database - 删除数据库
5. use_database - 选择要使用的数据库

表管理

1. list_tables - 列出数据库中的所有表
2. describe_table - 描述表结构
3. create_table - 创建新表
4. drop_table - 删除表

数据操作CRUD

1. select - 执行 SELECT 查询
2. insert - 插入数据到表
3. update - 更新表中的数据
4. delete - 从表中删除数据

SQL 执行

1. execute_sql - 执行 SQL 查询或命令

Schema 查询自然语言转 SQL 专用

1. get_database_schema - 获取整个数据库的完整 schema 信息所有表列类型约束外键关系
2. get_table_schema - 获取指定表的完整 schema 信息列名数据类型约束默认值是否可空等
3. get_foreign_keys - 获取表的外键关系信息理解表之间的关联
4. get_indexes - 获取表的索引信息
5. get_table_info - 获取表的统计信息行数引擎类型等
6. get_sample_data - 获取表的示例数据帮助理解数据结构和内容

自然语言转 SQL 支持

该 MCP 服务完全支持 agent 将自然语言转换为 SQL 查询通过以下工具agent 可以

1. 理解数据库结构

   • 使用 get_database_schema 获取整个数据库的完整结构
   • 使用 get_table_schema 获取特定表的详细列信息
   • 使用 get_foreign_keys 理解表之间的关联关系

2. 理解数据内容

   • 使用 get_sample_data 查看示例数据理解数据格式和内容
   • 使用 get_table_info 了解表的统计信息

3. 生成和执行 SQL

   • 基于 schema 信息生成准确的 SQL 查询
   • 使用 execute_sql 执行生成的 SQL
   • 或使用便捷的 select``insert``update``delete 工具

典型工作流程

当用户说"查询所有年龄大于 25 的用户"时agent 可以

1. 使用 get_database_schema 或 list_tables 找到用户表
2. 使用 get_table_schema 查看用户表的结构确认年龄字段名称如 age
3. 使用 get_sample_data 查看示例数据理解数据格式
4. 生成 SQLSELECT * FROM users WHERE age > 25
5. 使用 execute_sql 执行查询并返回结果

故障排除

常见问题

1. "Not connected" 错误

   • 检查配置文件路径是否正确
   • 确保 Node.js 在系统 PATH 中或使用完整路径
   • 重启 Cursor 应用
   • 验证 MySQL 服务正在运行Windows: net start mysql80

2. 连接失败

   • 确保 MySQL 服务已启动
   • 检查用户名和密码是否正确
   • 验证 MySQL 端口默认 3306是否可访问

3. 路径问题

   • Windows 路径建议使用正斜杠 / 或双反斜杠 \\
   • 确保路径中的文件确实存在

4. 依赖问题

   • 运行 npm install 确保所有依赖已安装
   • 确保使用 Node.js 18+ 版本

更多故障排除信息请参考 TROUBLESHOOTING.md

注意事项

• 确保 MySQL 服务已启动Windows: net start mysql80
• 用户名和密码通过命令行参数或环境变量传递
• 确保 Node.js 已安装并可在命令行中使用
• 对于自然语言转 SQL建议先使用 schema 查询工具了解数据库结构
• 不要将包含真实密码的配置文件提交到 Git 仓库

贡献

欢迎提交 Issue 和 Pull Request