MySQL MCP 服务器

一个用于 MySQL 数据库操作的 Model Context Protocol (MCP) 服务器，支持基于角色的权限控制和健康监控功能。

🚀 特性

• 数据库健康监控：实时连接状态与健康检查
• 基于角色的访问控制：可配置用户角色（只读、读写、管理员）
• 全面的数据库信息：模式、表状态及连接详情
• 安全查询执行：经过权限验证的 SQL 查询执行
• 多种构建格式：TypeScript 和 ESM 打包版本
• 自动注册系统：模块化工具处理器架构

📋 目录

• 配置
• 使用方法
• 用户角色与权限
• 可用工具
• API 参考
• 故障排查

⚙️ 配置

环境变量

# 数据库配置
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=your_username
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database

# 服务器配置
MYSQL_ROLE=readwrite
LANGUAGE=zh-CN

数据库配置

通过设置 MYSQL_HOST、MYSQL_PORT、MYSQL_USER、MYSQL_PASSWORD、MYSQL_DATABASE 环境变量来配置数据库信息

用户角色配置

通过设置 MYSQL_ROLE 环境变量来配置用户角色：

• readonly：只读访问（SELECT, SHOW, DESCRIBE）
• readwrite：读写访问（+ INSERT, UPDATE, DELETE）
• admin：完全访问（+ CREATE, DROP, ALTER, 管理命令）

语言配置

通过设置 LANGUAGE 环境变量来配置语言：en、zh-CN

🎯 使用方法

安装

你可以使用 NPM 全局安装这个包

npm install -g @jd-joycode/mcp-mysql-ts

与 MCP 客户端集成

添加到你的 MCP 客户端配置中：

{
  "mcpServers": {
    "mcp-mysql-ts": {
      "command": "npx",
      "args": ["-y", "@jd-joycode/mcp-mysql-ts"],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_user",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database",
        "MYSQL_ROLE": "readwrite",
        "LANGUAGE": "zh-CN"
      }
    }
  }
}

终端调式

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"mysql_health_check","arguments":{}}}' | MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_USER=your_user MYSQL_PASSWORD=your_password MYSQL_DATABASE=your_database MYSQL_ROLE=readwrite LANGUAGE=zh-CN npx -y @jd-joycode/mcp-mysql-ts

👥 用户角色与权限

只读角色（Readonly）

• ✅ SELECT 语句
• ✅ SHOW 命令
• ✅ DESCRIBE 命令
• ✅ 健康检查
• ✅ 数据库信息
• ❌ 数据修改
• ❌ 模式更改

读写角色（Readwrite）

• ✅ 所有只读权限
• ✅ INSERT 语句
• ✅ UPDATE 语句
• ✅ DELETE 语句
• ❌ 模式修改
• ❌ 管理命令

管理员角色（Admin）

• ✅ 所有读写权限
• ✅ CREATE 语句
• ✅ DROP 语句
• ✅ ALTER 语句
• ✅ 管理命令
• ✅ 用户管理

🔧 可用工具

mysql_health_check

检查数据库连接和健康状态。

参数: 无

示例响应:

{
  "status": "healthy",
  "database": "connected",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "connection": {
    "host": "127.0.0.1",
    "port": 3306,
    "database": "myapp"
  }
}

mysql_database_info

获取全面的数据库信息。

参数: 无

返回值: 数据库模式、表统计信息等

mysql_connection_info

获取当前连接信息和服务器状态。

参数: 无

返回值: 连接详细信息和服务器变量

mysql_table_status

获取所有数据库表的详细状态。

参数: 无

返回值: 表统计信息、行数、存储信息等

mysql_multi_query

执行多个 MySQL 语句，支持高级选项如注释移除、错误处理和详细报告。

参数:

• queries (字符串, 必填): 多条 SQL 语句，以分号分隔。
• stopOnError (布尔值, 可选): 遇到错误时停止执行，默认为 true。
• includeDetails (布尔值, 可选): 是否包含每条语句的详细执行信息，默认为 false。
• dryRun (布尔值, 可选): 解析并验证查询而不执行它们，默认为 false。

示例请求:

{
  "queries": "SELECT * FROM users; INSERT INTO logs (message) VALUES ('test');",
  "stopOnError": true,
  "includeDetails": false,
  "dryRun": false
}

mysql_query

执行单条或多条 MySQL 查询，支持自动注释移除和权限检查。

参数:

• query (字符串, 必填): 要执行的 SQL 查询或多个语句（支持以分号分隔）。
• multiStatement (布尔值, 可选): 启用多语句执行模式，默认为 true。
• stopOnError (布尔值, 可选): 遇到错误时停止执行，默认为 true。

示例请求:

{
  "query": "SELECT * FROM users; INSERT INTO logs (message) VALUES ('test');",
  "multiStatement": true,
  "stopOnError": true
}

返回值: 返回执行结果的总结，包括成功与失败的语句数量、受影响行数、平均执行时间等。如果是单语句执行，则返回该语句的结果及执行时间。

mysql_execute_sql_files

执行多个 SQL 文件，具有全面的错误处理、进度跟踪和详细报告。支持本地文件路径和 HTTP/HTTPS URL。

参数:

• filePaths (字符串, 必填): SQL 文件绝对路径或HTTP/HTTPS URL的逗号分隔列表（例如：/path/to/file1.sql,https://example.com/file2.sql,/path/to/file3.sql）。
• stopOnFileError (布尔值, 可选): 当某个文件加载失败时停止执行，默认为 true。
• stopOnStatementError (布尔值, 可选): 当任何 SQL 语句执行失败时停止执行，默认为 true。
• includeFileContent (布尔值, 可选): 在响应中包含原始文件内容（用于调试），默认为 false。
• includeStatementDetails (布尔值, 可选): 包含每条语句的详细执行结果，默认为 false。
• dryRun (布尔值, 可选): 解析并验证文件而不执行 SQL 语句，默认为 false。
• maxFileSize (数值, 可选): 本地文件和下载文件的最大文件大小（字节），默认为 10485760。
• downloadTimeout (数值, 可选): URL下载超时时间（毫秒），默认为 30000。
• tempDir (字符串, 可选): 临时存储下载文件的目录，默认为 /tmp。
• cleanupTempFiles (布尔值, 可选): 执行完成后自动删除下载的临时文件，默认为 true。

示例请求:

{
  "filePaths": "/path/to/schema.sql,/path/to/data.sql",
  "stopOnFileError": true,
  "stopOnStatementError": true,
  "includeFileContent": false,
  "includeStatementDetails": false,
  "dryRun": false,
  "maxFileSize": 10485760
}

返回值: 返回所有 SQL 文件的执行总结，包括成功与失败的文件数量、总执行时间、每个文件的执行状态以及可选的详细语句执行信息。

📚 API 参考

响应格式

所有工具响应遵循以下格式：

interface ToolResponse {
  content: Array<{
    type: 'text';
    text: string;
  }>;
}

错误处理

错误以标准化格式返回：

{
  "content": [{
    "type": "text",
    "text": "错误：管理员操作权限不足"
  }]
}

数据库连接

服务器自动管理数据库连接，包括：

• 连接池
• 自动重连
• 连接健康监测
• 优雅关闭处理

🐛 故障排查

常见问题

连接被拒绝

错误：connect ECONNREFUSED 127.0.0.1:3306

解决方法：确认 MySQL 正在运行且连接信息正确。

权限不足

错误：写操作权限不足