@hyperlinked/mcp-mysql-server 中文说明

[English | 中文文档]

基于 Model Context Protocol (MCP) 的标准化 MySQL 数据库操作服务端。该服务器使 AI 模型和应用程序能够通过一致的 JSON-RPC 2.0 接口安全地与 MySQL 数据库交互。

✨ 特性

• 多种传输模式: 支持 stdio（默认）用于桌面客户端和基于 SSE 的 HTTP 传输用于 Web 应用程序
• 完整的工具集: 7 个专用工具用于数据库操作，包括查询、执行、表列表和性能分析
• 安全优先: 所有查询均使用参数化预处理语句，防止 SQL 注入攻击
• 连接管理: 自动连接池，可配置限制和清理
• TypeScript 支持: 完整的类型定义，提升开发体验
• Docker 就绪: 预配置的 Docker 和 Docker Compose 支持，用于容器化部署
• 详细的错误处理: 连接问题、无效查询和数据库错误的清晰错误消息

🚀 快速开始

前置要求

• Node.js 14.x 或更高版本
• MySQL 数据库服务器
• MCP 兼容客户端（Claude Desktop、CodeBuddy 等）

安装

通过 Smithery（推荐用于 Claude Desktop）

npx -y @smithery/cli install @hyperlinked/mcp-mysql-server --client claude

通过 npm

# 直接运行
npx @hyperlinked/mcp-mysql-server

# 或全局安装
npm install -g @hyperlinked/mcp-mysql-server
mcp-mysql-server

从源码安装

git clone https://github.com/huangfeng19820712/mcp-mysql-server.git
cd mcp-mysql-server
npm install
npm run build
npm start

⚙️ 配置

方法一：MySQL 连接 URL（推荐）

npx @hyperlinked/mcp-mysql-server mysql://user:password@localhost:3306/database

方法二：环境变量

创建 .env 文件：

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

# 连接池配置
CONNECTION_LIMIT=10
QUEUE_LIMIT=0

然后启动服务器：

npx @hyperlinked/mcp-mysql-server

方法三：MCP 客户端配置

用于 Claude Desktop (claude_desktop_config.json)：

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@hyperlinked/mcp-mysql-server", "mysql://user:password@localhost:3306/database"]
    }
  }
}

在 MCP 配置中使用环境变量：

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@hyperlinked/mcp-mysql-server"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

🔌 传输选项

1. Stdio 传输（默认）

适用于 Claude Desktop 等桌面 MCP 客户端。使用标准输入/输出进行通信。

# 使用 stdio 传输启动
npx @hyperlinked/mcp-mysql-server mysql://user:password@localhost:3306/database

2. 流式 HTTP 传输（基于 SSE）

适用于 Web 应用程序或远程连接。通过 HTTP 使用服务器发送事件。

# 使用 SSE 传输在默认端口 3000 启动
npx @hyperlinked/mcp-mysql-server --transport sse mysql://user:password@localhost:3306/database

# 使用 SSE 传输在自定义端口启动
npx @hyperlinked/mcp-mysql-server --transport sse --port 8080 mysql://user:password@localhost:3306/database

使用 SSE 传输时：

• 连接到：http://localhost:3000/sse（或您的自定义端口）
• 发送消息到：http://localhost:3000/message?sessionId=<会话ID>
• 支持跨域请求的 CORS

🐳 Docker 部署

使用 Docker Compose（推荐）

# docker-compose.yaml
services:
  mcp-mysql-server:
    image: mcp-mysql-server:latest
    container_name: mcp-mysql-server
    restart: unless-stopped
    environment:
      - MYSQL_HOST=localhost
      - MYSQL_USER=root
      - MYSQL_PASSWORD=your_password
      - MYSQL_DATABASE=your_database
      - MYSQL_PORT=3306
      - CONNECTION_LIMIT=10
    ports:
      - "3000:3000"

# 构建并运行
docker-compose up -d

# 查看日志
docker-compose logs -f

直接使用 Docker

# 构建镜像
docker build -t mcp-mysql-server .

# 运行容器
docker run -p 3000:3000 \
  -e MYSQL_HOST=localhost \
  -e MYSQL_USER=root \
  -e MYSQL_PASSWORD=your_password \
  -e MYSQL_DATABASE=your_database \
  mcp-mysql-server

🛠️ 可用工具

1. connect_db

建立与 MySQL 数据库的连接。可以使用 URL 字符串或单独的连接参数调用。

use_mcp_tool({
  server_name: "mysql",
  tool_name: "connect_db",
  arguments: {
    url: "mysql://user:password@host:port/database"
  }
});

// 或使用单独的参数
use_mcp_tool({
  server_name: "mysql",
  tool_name: "connect_db",
  arguments: {
    host: "localhost",
    user: "your_user",
    password: "your_password",
    database: "your_database",
    port: 3306
  }
});

2. query

执行 SELECT 查询，支持可选的预处理语句参数。

// 简单查询
use_mcp_tool({
  server_name: "mysql",
  tool_name: "query",
  arguments: {
    sql: "SELECT * FROM users"
  }
});

// 参数化查询
use_mcp_tool({
  server_name: "mysql",
  tool_name: "query",
  arguments: {
    sql: "SELECT * FROM users WHERE age > ? AND status = ?",
    params: [18, "active"]
  }
});

3. execute

执行 INSERT、UPDATE 或 DELETE 查询，支持可选的预处理语句参数。

// 插入数据
use_mcp_tool({
  server_name: "mysql",
  tool_name: "execute",
  arguments: {
    sql: "INSERT INTO users (name, email) VALUES (?, ?)",
    params: ["John Doe", "[email protected]"]
  }
});

// 更新数据
use_mcp_tool({
  server_name: "mysql",
  tool_name: "execute",
  arguments: {
    sql: "UPDATE users SET status = ? WHERE id = ?",
    params: ["inactive", 123]
  }
});

// 删除数据
use_mcp_tool({
  server_name: "mysql",
  tool_name: "execute",
  arguments: {
    sql: "DELETE FROM users WHERE id = ?",
    params: [456]
  }
});

4. list_tables

列出连接数据库中的所有表。

use_mcp_tool({
  server_name: "mysql",
  tool_name: "list_tables",
  arguments: {}
});

5. describe_table

获取特定表的结构，包括列名、数据类型和约束。

use_mcp_tool({
  server_name: "mysql",
  tool_name: "describe_table",
  arguments: {
    table: "users"
  }
});

6. show_statement

执行 SHOW 语句（例如 SHOW STATUS、SHOW VARIABLES、SHOW TABLES）。

use_mcp_tool({
  server_name: "mysql",
  tool_name: "show_statement",
  arguments: {
    sql: "SHOW VARIABLES LIKE 'max_connections'"
  }
});

use_mcp_tool({
  server_name: "mysql",
  tool_name: "show_statement",
  arguments: {
    sql: "SHOW STATUS LIKE 'Threads_connected'"
  }
});

7. explain

使用 EXPLAIN 分析 SQL 查询性能。返回执行计划详情，包括访问类型、扫描行数和可能的优化建议。

use_mcp_tool({
  server_name: "mysql",
  tool_name: "explain",
  arguments: {
    sql: "SELECT * FROM users WHERE age > 18 AND status = 'active'"
  }
});

📝 使用示例

连接数据库

// 首先建立数据库连接
use_mcp_tool({
  server_name: "mysql",
  tool_name: "connect_db",
  arguments: {
    host: "localhost",
    user: "app_user",
    password: "secure_password",
    database: "production_db"
  }
});

执行 CRUD 操作

// 查询用户数据
const userQuery = await use_mcp_tool({
  server_name: "mysql",
  tool_name: "query",
  arguments: {
    sql: "SELECT id, name, email FROM users WHERE active = ?",
    params: [true]
  }
});

// 添加新产品
const insertResult = await use_mcp_tool({
  server_name: "mysql",
  tool_name: "execute",
  arguments: {
    sql: "INSERT INTO products (name, price, stock) VALUES (?, ?, ?)",
    params: ["New Product", 29.99, 100]
  }
});

数据库模式探索

// 列出所有表
const tables = await use_mcp_tool({
  server_name: "mysql",
  tool_name: "list_tables",
  arguments: {}
});

// 检查表结构
const tableStructure = await use_mcp_tool({
  server_name: "mysql",
  tool_name: "describe_table",
  arguments: {
    table: "orders"
  }
});

性能分析

// 分析慢查询
const explainResult = await use_mcp_tool({
  server_name: "mysql",
  tool_name: "explain",
  arguments: {
    sql: "SELECT * FROM orders WHERE customer_id = 123 AND status = 'pending'"
  }
});

🚨 错误处理

服务器为常见场景提供详细的错误消息：

| 错误类型 | 描述 | 解决方案 | |----------|------|----------| | 连接失败 | 无法连接到 MySQL 服务器 | 验证凭据，检查网络连接 | | 无效查询 | SQL 语法错误或无效操作 | 检查 SQL 语法，确认表/列名 | | 缺少参数 | 未提供必需的参数 | 确保包含所有必填字段 | | 权限不足 | 数据库用户权限不足 | 授予数据库用户适当的权限 | | 资源限制 | 连接池耗尽或超时 | 调整 CONNECTION_LIMIT 或优化查询 |

🔒 安全最佳实践

1. 凭据管理

   • 切勿在源代码中硬编码数据库凭据
   • 使用环境变量或安全的配置文件
   • 为数据库用户实施最小权限原则

2. SQL 注入防护

   • 始终使用参数化查询（所有工具均提供）
   • 避免字符串拼接 SQL 语句
   • 在传递到数据库之前验证用户输入

3. 连接安全

   • 在生产环境中使用 TLS/SSL 进行数据库连接
   • 定期轮换数据库密码
   • 监控连接日志以发现可疑活动

4. 网络安全

   • 将数据库访问限制在受信任的网络
   • 使用防火墙限制端口暴露
   • 考虑使用 VPN 或 SSH 隧道进行远程连接

🏗️ 项目结构

mcp-mysql-server/
├── src/
│   ├── index.ts          # 主服务器入口点
│   └── handlers.ts       # 工具实现处理程序
├── build/                # 编译的 JavaScript 输出
├── examples/
│   └── sse-client.ts    # SSE 客户端示例
├── Dockerfile           # Docker 容器配置
├── docker-compose.yaml  # Docker Compose 配置
├── package.json         # 项目依赖和脚本
├── tsconfig.json        # TypeScript 配置
└── logs/                # 应用程序日志目录

🧪 开发

从源码构建

# 克隆仓库
git clone https://github.com/huangfeng19820712/mcp-mysql-server.git
cd mcp-mysql-server

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm test

# 以监视模式启动开发服务器
npm run watch

可用的 npm 脚本

npm run build           # 构建项目
npm run watch           # 开发监视模式
npm run inspector       # 使用 MCP 检查器运行
npm start              # 启动服务器
npm run start:sse      # 使用 SSE 传输启动
npm test              # 运行测试套件

🤝 贡献

欢迎贡献！以下是如何提供帮助：

1. 报告错误: 提供详细的重现步骤来开启问题
2. 建议功能: 分享新工具或改进的想法
3. 提交 Pull Request: 修复错误或实现新功能
4. 改进文档: 帮助使项目更易于访问

请确保您的代码遵循现有风格并包含适当的测试。

📄 许可证

MIT 许可证 - 详见 LICENSE 文件。

📚 额外资源

• Model Context Protocol 文档
• MySQL 文档
• 详细使用指南
• 示例