@liangshanli/mcp-server-mysql

v3.0.0

Published

2 months ago

MCP MySQL server with DDL support, permission control and operation logs

0High
0Medium
0Low

liangshanli1983

mcp mysql server ddl database

MCP MySQL 服务器

一个支持DDL操作、权限控制和操作日志的MCP MySQL服务器。

版本历史

v3.0.0 (最新版本)

✅ 只读模式：新增 READONLY 环境变量 - 启用后只允许执行 SELECT 和 SHOW 命令（最高优先级检查）
✅ 工具前缀支持：新增 TOOL_PREFIX 环境变量，用于工具名称隔离和配置分离
✅ 项目品牌：新增 PROJECT_NAME 环境变量，用于自定义工具描述
✅ 增强权限检查：改进了 check_permissions 工具，包含详细消息和只读模式警告
✅ 默认日志路径：将默认日志目录从 ./logs 改为 ./.setting（如果设置了前缀则为 ./.setting.<TOOL_PREFIX>）
✅ 多实例支持：完整支持运行多个 MySQL 服务器实例，配置相互隔离
✅ 改进 CLI：更新 CLI 以支持所有新环境变量和日志路径配置

v2.0.1

✅ DDL SQL 日志记录：新增专门的 DDL SQL 操作日志记录到 ddl.sql 文件
✅ 仅记录成功操作：只有成功的 DDL 操作才会记录到 SQL 文件中
✅ 时间戳条目：每个 DDL 操作都包含精确的时间戳注释
✅ 自动格式化：SQL 语句自动格式化并添加分号结尾
✅ 新工具：新增 get_ddl_sql_logs 工具用于查询 DDL 操作历史
✅ 增强日志：改进日志配置，支持独立的 DDL 日志文件

v2.0.0

✅ 初始版本，支持 DDL 操作
✅ 权限控制系统
✅ 操作日志记录
✅ 连接池管理

功能特性

✅ 支持SQL查询执行（DDL和DML）
✅ 数据库信息获取
✅ 操作日志记录
✅ 连接池管理
✅ 自动重连机制
✅ 健康检查
✅ 错误处理和恢复

安装

全局安装（推荐）

npm install -g @liangshanli/mcp-server-mysql

本地安装

npm install @liangshanli/mcp-server-mysql

从源码安装

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

配置

设置环境变量：

export MYSQL_HOST=localhost
export MYSQL_PORT=3306
export MYSQL_USER=root
export MYSQL_PASSWORD=your_password
export MYSQL_DATABASE=your_database
export READONLY=false
export ALLOW_DDL=true
export ALLOW_DROP=false
export ALLOW_DELETE=false

# 可选：工具前缀，用于配置隔离
export TOOL_PREFIX="projA"

# 可选：项目品牌名称
export PROJECT_NAME="MyProject"

使用方法

1. 全局安装后直接运行

mcp-server-mysql

2. 使用 npx 运行（推荐）

npx @liangshanli/mcp-server-mysql

3. 直接启动（源码安装）

npm start

4. 托管启动（推荐用于生产环境）

npm run start-managed

托管启动提供以下功能：

自动重启（最多10次）
错误恢复
进程管理
日志记录

5. 开发模式

npm run dev

编辑器集成

Cursor 编辑器配置

在项目根目录创建 .cursor/mcp.json 文件：

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["@liangshanli/mcp-server-mysql"],
      "env": {
        "MYSQL_HOST": "your_host",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_user",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database",
        "READONLY": "false",
        "ALLOW_DDL": "false",
        "ALLOW_DROP": "false",
        "ALLOW_DELETE": "false",
        "TOOL_PREFIX": "projA",
        "PROJECT_NAME": "MyProject"
      }
    }
  }
}

VS Code 配置

安装 VS Code 的 MCP 扩展
创建 .vscode/settings.json 文件：

{
  "mcp.servers": {
    "mysql": {
      "command": "npx",
      "args": ["@liangshanli/mcp-server-mysql"],
      "env": {
        "MYSQL_HOST": "your_host",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_user",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database",
        "READONLY": "false",
        "ALLOW_DDL": "false",
        "ALLOW_DROP": "false",
        "ALLOW_DELETE": "false",
        "TOOL_PREFIX": "projA",
        "PROJECT_NAME": "MyProject"
      }
    }
  }
}

多 MySQL 服务器实例支持

您可以配置多个 MySQL 服务器实例，使用不同的 TOOL_PREFIX 和 PROJECT_NAME 来隔离工具和配置。这在需要同时连接到多个数据库时非常有用。

示例：Cursor 编辑器配置

创建 .cursor/mcp.json 文件：

{
  "mcpServers": {
    "local-mysql": {
      "disabled": false,
      "timeout": 60,
      "command": "npx",
      "args": ["@liangshanli/mcp-server-mysql"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_user",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database",
        "ALLOW_DDL": "true",
        "ALLOW_DROP": "true",
        "ALLOW_DELETE": "false",
        "TOOL_PREFIX": "local",
        "PROJECT_NAME": "local-mysql"
      }
    },
    "online-mysql": {
      "disabled": false,
      "timeout": 60,
      "command": "npx",
      "args": ["@liangshanli/mcp-server-mysql"],
      "env": {
        "MYSQL_HOST": "your_remote_host",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_user",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database",
        "READONLY": "true",
        "ALLOW_DDL": "false",
        "ALLOW_DROP": "false",
        "ALLOW_DELETE": "false",
        "TOOL_PREFIX": "online",
        "PROJECT_NAME": "online-mysql"
      }
    }
  }
}

多实例的优势：

工具隔离：每个实例都有自己独立的工具名称（例如：local_sql_query、online_sql_query）
配置隔离：日志和 DDL 文件存储在独立的目录中（例如：./.setting.local/、./.setting.online/）
不同权限：为每个实例配置不同的权限级别（例如：生产环境只读，开发环境完全访问）
项目品牌：每个实例可以有自己的项目名称，便于识别

注意：使用多个实例时，工具名称会带有 TOOL_PREFIX 前缀。例如：

local_sql_query - 查询本地数据库
online_sql_query - 查询在线数据库（只读）

作为MCP服务器

服务器启动后，通过stdin/stdout与MCP客户端通信：

{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18"}}

可用工具

sql_query: 执行SQL查询

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "sql_query",
    "arguments": {
      "sql": "SELECT * FROM users LIMIT 10"
    }
  }
}

get_database_info: 获取数据库信息

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_database_info",
    "arguments": {}
  }
}

get_operation_logs: 获取操作日志

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get_operation_logs",
    "arguments": {
      "limit": 50,
      "offset": 0
    }
  }
}

get_ddl_sql_logs: 获取 DDL SQL 操作日志 (v2.0.1+)

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "get_ddl_sql_logs",
    "arguments": {
      "limit": 50,
      "offset": 0
    }
  }
}

check_permissions: 检查数据库权限

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "check_permissions",
    "arguments": {}
  }
}

连接池特性

自动创建: 在notifications/initialized时自动创建连接池
健康检查: 每5分钟检查连接池状态
自动重连: 连接池失效时自动重新创建
连接复用: 使用连接池提高性能
优雅关闭: 服务器关闭时正确释放连接

日志

常规日志

日志文件位置：./.setting/mcp-mysql.log (如果设置了TOOL_PREFIX则为 ./.setting.<TOOL_PREFIX>/mcp-mysql.log)

记录内容：

所有请求和响应
SQL操作记录
错误信息
连接池状态变化

DDL SQL 日志 (v2.0.1+)

DDL 日志文件位置：./.setting/ddl.sql (如果设置了TOOL_PREFIX则为 ./.setting.<TOOL_PREFIX>/ddl.sql)

功能特性：

仅记录成功操作：只有成功的 DDL 操作才会被记录
时间戳条目：每个操作都包含精确的时间戳注释
自动格式化：SQL 语句自动格式化并添加分号结尾
可执行格式：可以直接执行来重建数据库结构

DDL 日志格式示例：

# 2024-01-15 14:23:45
CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(100));
# 2024-01-15 14:24:12
ALTER TABLE users ADD COLUMN email VARCHAR(255);
# 2024-01-15 14:25:33
CREATE INDEX idx_email ON users(email);

DDL 日志记录优势

🔄 数据库同步

生产环境同步：轻松将开发环境的数据库结构变更同步到生产环境
多环境部署：在测试、预发布、生产等多个环境中应用相同的 DDL 变更
回滚支持：维护完整的结构变更历史，便于快速回滚操作

📋 开发工作流

结构版本控制：通过时间戳记录跟踪数据库演进历史
团队协作：通过可执行的 SQL 文件与团队成员分享数据库结构变更
代码审查：将数据库变更与应用程序代码变更一起进行审查

🛡️ 运营卓越

审计跟踪：维护所有数据库结构修改的全面审计日志
合规性：满足数据库变更跟踪的监管要求
灾难恢复：在数据丢失情况下快速从 DDL 日志重建数据库结构

⚡ 性能与可靠性

清洁执行：只记录成功操作，确保脚本执行的可靠性
错误预防：排除失败操作，防止脚本执行错误
自动格式化：一致的 SQL 格式化减少手动错误并提高可读性

错误处理

单个请求错误不会影响整个服务器
连接池错误会自动恢复
进程异常会自动重启（托管模式）

环境变量

| 变量名 | 默认值 | 说明 | |--------|--------|------| | MYSQL_HOST | localhost | MySQL主机地址 | | MYSQL_PORT | 3306 | MySQL端口 | | MYSQL_USER | root | MySQL用户名 | | MYSQL_PASSWORD | | MySQL密码 | | MYSQL_DATABASE | | 数据库名 | | READONLY | false | 如果设置为'true'，只允许执行SELECT和SHOW命令。此检查具有最高优先级，会覆盖所有其他权限设置 | | ALLOW_DDL | false | 是否允许DDL操作（CREATE、ALTER、TRUNCATE、RENAME、COMMENT）。设置为'true'启用 | | ALLOW_DROP | false | 是否允许DROP操作。设置为'true'启用 | | ALLOW_DELETE | false | 是否允许DELETE操作。设置为'true'启用 | | TOOL_PREFIX | | 可选工具前缀，用于工具名称和配置隔离。示例：export TOOL_PREFIX="projA" | | PROJECT_NAME | | 可选项目品牌名称，用于工具描述 | | MCP_LOG_DIR | ./.setting (如果设置了TOOL_PREFIX则为 ./.setting.<TOOL_PREFIX>) | 日志目录 | | MCP_LOG_FILE | mcp-mysql.log | 日志文件名 | | MCP_DDL_LOG_FILE | ddl.sql | DDL SQL 日志文件名 (v2.0.1+) |

开发

项目结构

mcpmysql/
├── src/
│   └── server-final.js    # 主服务器文件
├── start-server.js        # 托管启动脚本
├── package.json
└── README.md

测试

npm test

快速开始

1. 安装包

npm install -g @liangshanli/mcp-server-mysql

2. 配置环境变量

export MYSQL_HOST=localhost
export MYSQL_PORT=3306
export MYSQL_USER=root
export MYSQL_PASSWORD=your_password
export MYSQL_DATABASE=your_database
export READONLY=false
export ALLOW_DDL=false
export ALLOW_DROP=false
export ALLOW_DELETE=false

**权限控制示例：**
```bash
# 只读模式：只允许SELECT和SHOW命令（最高优先级）
export READONLY=true

# 默认：禁用所有破坏性操作（安全模式）
export READONLY=false
export ALLOW_DDL=false
export ALLOW_DROP=false
export ALLOW_DELETE=false

# 允许DDL但禁用DROP和DELETE
export READONLY=false
export ALLOW_DDL=true
export ALLOW_DROP=false
export ALLOW_DELETE=false

# 允许所有操作但禁用DELETE
export READONLY=false
export ALLOW_DDL=true
export ALLOW_DROP=true
export ALLOW_DELETE=false

# 启用所有操作（谨慎使用）
export READONLY=false
export ALLOW_DDL=true
export ALLOW_DROP=true
export ALLOW_DELETE=true

3. 运行服务器

mcp-server-mysql

许可证

MIT