使用说明

MCP MySQL服务器

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

版本历史记录

v2.0.2（最新版本）

✅ 配置文件支持：添加了JSON配置文件支持 --config 参数
✅ 命令行参数：已添加 --help 和 --config 命令行选项
✅ 向后兼容：维护环境变量支持作为后备
✅ 增强文档：更新了README，其中包含配置示例和使用说明

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 @bobliu1996/mcp-server-mysql

本地安装

npm install @bobliu1996/mcp-server-mysql

来源

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

配置

配置文件

服务器现在使用JSON配置文件并支持 --config 参数，用于指定配置文件路径。

配置文件结构

{
  "mysql": {
    "host": "localhost",
    "port": 3306,
    "user": "root",
    "password": "",
    "database": ""
  },
  "permissions": {
    "allowDDL": false,
    "allowDrop": false,
    "allowDelete": false
  },
  "logging": {
    "logDir": "./logs",
    "logFile": "mcp-mysql.log",
    "ddlLogFile": "ddl.sql"
  }
}

配置参数

参数	说明	默认值
`mysql.host`	MySQL服务器地址	`localhost`
`mysql.port`	MySQL服务器端口	`3306`
`mysql.user`	MySQL用户名	`root`
`mysql.password`	MySQL密码	``
`permissions.allowDDL`	允许DDL操作	`false`
`permissions.allowDrop`	允许DROP操作	`false`
`permissions.allowDelete`	允许DELETE操作	`false`
`logging.logDir`	日志目录	`./logs`
`logging.logFile`	日志文件名	`mcp-mysql.log`
`logging.ddlLogFile`	DDL日志文件名	`ddl.sql`

配置示例

基本配置（config.json）：

{
  "mysql": {
    "host": "localhost",
    "port": 3306,
    "user": "root",
    "password": "your_password",
    "database": "test_db"
  },
  "permissions": {
    "allowDDL": true,
    "allowDrop": false,
    "allowDelete": true
  },
  "logging": {
    "logDir": "./logs",
    "logFile": "mcp-mysql.log",
    "ddlLogFile": "ddl.sql"
  }
}

用法

1.使用默认配置文件

# Direct run with default config.json
mcp-server-mysql

# Using npx (Recommended)
npx @bobliu1996/mcp-server-mysql

2.指定配置文件

# Use custom configuration file
mcp-server-mysql --config /path/to/your-config.json

# Using npx
npx @bobliu1996/mcp-server-mysql --config ./my-config.json

3.显示帮助

mcp-server-mysql --help

4.直接启动（源安装）

# Use default configuration
npm start

# Use custom configuration
npm start -- --config ./my-config.json

5.管理启动（建议用于生产）

# Use default configuration
npm run start-managed

# Use custom configuration
npm run start-managed -- --config ./prod-config.json

管理启动提供：

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

6.发展模式

npm run dev

编辑器集成

光标编辑器配置

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

使用配置文件（推荐）：

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["@bobliu1996/mcp-server-mysql", "--config", "./config.json"]
    }
  }
}

多实例配置（支持同时运行多台服务器）：

{
  "mcpServers": {
    "mysql-dev": {
      "command": "npx",
      "args": ["@bobliu1996/mcp-server-mysql", "--config", "./config-dev.json"]
    },
    "mysql-prod": {
      "command": "npx",
      "args": ["@bobliu1996/mcp-server-mysql", "--config", "./config-prod.json"]
    }
  }
}

工具名称隔离：每个服务器实例都会自动为工具名称添加一个实例前缀：

开发实例: dev_sql_query, dev_get_database_info等等。
生产实例: prod_sql_query, prod_get_database_info等等。

使用环境变量（向后兼容）：

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

VS代码配置

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

使用配置文件（推荐）：

{
  "mcp.servers": {
    "mysql": {
      "command": "npx",
      "args": ["@bobliu1996/mcp-server-mysql", "--config", "./config.json"]
    }
  }
}

使用环境变量（向后兼容）：

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

作为MCP服务器

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

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

可用工具

sqlquery：执行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_dl_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
    }
  }
}

检查权限：检查数据库权限

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

连接池功能

自动创建：在上自动创建连接池 notifications/initialized
健康检查：每5分钟检查一次连接池状态
自动重新连接：失败时自动重新创建连接池
连接复用：使用连接池以获得更好的性能
平滑关闭：服务器关闭时正确释放连接

日志记录

常规日志

日志文件位置： ./logs/mcp-mysql.log

记录的内容：

所有请求和答复
SQL操作记录
错误消息
连接池状态更改

DDL SQL日志（v2.0.1+）

DDL日志文件位置： ./logs/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主机	本地主机	MYSQL主机地址
MYSQL端口	3306	MYSQL端口
MYSQL用户名	root	MYSQL用户名
MYSQL密码		MYSQL密码
MYSQL数据库		数据库名称
ALLOW_DDL	false	是否允许DDL操作（CREATE、ALTER、TRUNCATE、RENAME、COMMENT）。设置为“true”以启用
ALLOW_DROP	false	是否允许DROP操作。设置为“true”以启用
ALLOW_DELETE	false	是否允许DELETE操作。设置为“true”以启用
MCP_LOG_DIR	。/logs	日志目录
MCP_LOG_FILE	MCP-mysql.LOG	日志文件名
MCP_DDL_LOG_FILE	DDL.sql	DDL sql日志文件名（v2.0.1+）

发展

项目结构

mcpmysql/
├── src/
│   └── server-final.js    # Main server file
├── start-server.js        # Managed startup script
├── package.json
└── README.md

测试

npm test

快速开始

1.安装软件包

npm install -g @bobliu1996/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 ALLOW_DDL=false
export ALLOW_DROP=false
export ALLOW_DELETE=false

权限控制示例：

# Default: Disable all destructive operations (safe mode)
export ALLOW_DDL=false
export ALLOW_DROP=false
export ALLOW_DELETE=false

# Allow DDL but disable DROP and DELETE
export ALLOW_DDL=true
export ALLOW_DROP=false
export ALLOW_DELETE=false

# Allow everything except DELETE
export ALLOW_DDL=true
export ALLOW_DROP=true
export ALLOW_DELETE=false

# Enable all operations (use with caution)
export ALLOW_DDL=true
export ALLOW_DROP=true
export ALLOW_DELETE=true

3.运行服务器

mcp-server-mysql

许可证

麻省理工学院