MCP MySQL Server

MCP MySQL Server

MCP MySQL Server 是一个基于 Go 的 MCP 服务实现，提供 MySQL 数据库交互功能，允许 MCP 客户端（例如 Claude Desktop）执行数据库操作。

功能

• 符合 MCP 规范：提供基于 JSON-RPC 的接口，用于按照 MCP 规范执行工具。
• MySQL 操作：支持查询、架构检查以及（可选的）数据操作等数据库操作。
• 只读模式：可选限制，防止修改数据。
• 查询计划验证：可选使用 EXPLAIN 分析来验证查询安全性。
• URL 风格的连接字符串：支持标准 URL 风格的数据库连接字符串，例如 mysql://user:pass@host:port/dbname。
• 精简容器：使用 Google 的 distroless 构建，以提升安全性并减小镜像体积。

要求

• Docker（推荐）

本地开发所需：

• Go 1.24 或更高版本
• MySQL 服务（本地或远程）

使用 Docker（推荐）

# Pull the image
docker pull cnosuke/mcp-mysql:latest

# Run with default settings
docker run -i --rm cnosuke/mcp-mysql:latest

# Run with custom MySQL connection
docker run -i --rm \
  -e MYSQL_HOST=your-mysql-host \
  -e MYSQL_PORT=3306 \
  -e MYSQL_USER=your-username \
  -e MYSQL_PASSWORD=your-password \
  -e MYSQL_DATABASE=your-database \
  cnosuke/mcp-mysql:latest

# Run in read-only mode
docker run -i --rm \
  -e MYSQL_HOST=your-mysql-host \
  -e MYSQL_USER=your-username \
  -e MYSQL_PASSWORD=your-password \
  -e MYSQL_DATABASE=your-database \
  -e MYSQL_READ_ONLY=true \
  cnosuke/mcp-mysql:latest

与 Claude Desktop 配合使用（Docker）

若要使用 Docker 与 Claude Desktop 集成，请在 claude_desktop_config.json 文件中添加一项：

{
  "mcpServers": {
    "mysql": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "cnosuke/mcp-mysql:latest"],
      "env": {
        "MYSQL_HOST": "your-mysql-host",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your-username",
        "MYSQL_PASSWORD": "your-password",
        "MYSQL_DATABASE": "your-database",
        "MYSQL_READ_ONLY": "false"
      }
    }
  }
}

构建和运行（Go 二进制文件）

也可以直接构建并运行 Go 二进制文件：

# Build the server
make

# Run the server
./bin/mcp-mysql server --config=config.yml

与 Claude Desktop 配合使用（Go 二进制文件）

若要使用 Go 二进制文件与 Claude Desktop 集成，请在 claude_desktop_config.json 文件中添加一项：

{
  "mcpServers": {
    "mysql": {
      "command": "./bin/mcp-mysql",
      "args": ["server"],
      "env": {
        "LOG_PATH": "mcp-mysql.log",
        "DEBUG": "false",
        "MYSQL_HOST": "your-mysql-host",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your-username",
        "MYSQL_PASSWORD": "your-password",
        "MYSQL_DATABASE": "your-database",
        "MYSQL_READ_ONLY": "false"
      }
    }
  }
}

Docker 镜像详情

本项目使用 Google 的 distroless 容器镜像作为最终的 Docker 镜像。gcr.io/distroless/static 基础镜像提供：

• 最小攻击面——仅包含必要组件
• 更小的镜像体积——不含 shell、包管理器或其他不必要的二进制文件
• 更高的安全性——减少潜在漏洞的数量

Docker 镜像采用多阶段构建流程：

1. 第一阶段使用 Go Alpine 构建应用程序
2. 第二阶段使用仅包含编译后二进制文件的 distroless/static

配置

服务通过 YAML 文件（默认：config.yml）或环境变量进行配置：

log: 'path/to/mcp-mysql.log' # Log file path, if empty no log will be produced
debug: false # Enable debug mode for verbose logging

mysql:
  host: 'localhost'
  user: 'root'
  password: ''
  port: 3306
  database: ''
  dsn: ''
  read_only: false
  explain_check: false

连接选项

可以通过以下三种方式指定 MySQL 连接详情（按优先级从高到低排列）：

1. 工具参数：调用任意工具时，直接传入 dsn 参数
2. 配置中的 DSN：在配置文件中设置 mysql.dsn 的值
3. 单独参数：在配置文件中设置各项连接参数

如果以上方式均未提供连接信息，服务会返回错误消息，提示你提供连接详情。

配置选项

• mysql.host：MySQL 服务主机名（默认值：'localhost'）
• mysql.user：MySQL 用户名（默认值：'root'）
• mysql.password：MySQL 密码
• mysql.port：MySQL 端口（默认值：3306）
• mysql.database：MySQL 数据库名称
• mysql.dsn：MySQL DSN（数据源名称）字符串。如果提供此项，将覆盖各项单独的连接参数
• mysql.read_only：启用只读模式。在此模式下，仅可使用名称以 list、read_ 和 desc_ 开头的工具
• mysql.explain_check：执行查询前，使用 EXPLAIN 检查查询计划

可以使用环境变量覆盖配置：

• LOG_PATH：日志文件路径
• DEBUG：启用调试模式（true/false）
• MYSQL_HOST：MySQL 服务主机名
• MYSQL_PORT：MySQL 服务端口
• MYSQL_USER：MySQL 用户名
• MYSQL_PASSWORD：MySQL 密码
• MYSQL_DATABASE：MySQL 数据库名称
• MYSQL_DSN：MySQL DSN 字符串
• MYSQL_READ_ONLY：启用只读模式（true/false）
• MYSQL_EXPLAIN_CHECK：启用查询计划检查（true/false）

日志记录

日志行为由配置控制：

• 如果在配置文件中设置了 log，日志将写入指定文件
• 如果 log 为空，则不会生成日志
• 设置 debug: true 可输出更详细的日志

MCP 服务工具

MCP 客户端通过向服务发送 JSON‐RPC 请求来执行各种工具。支持以下 MCP 工具：

架构工具

1. list_database

   • 列出 MySQL 服务中的所有数据库。
   • 参数：
     • dsn（可选）：用于覆盖配置的 MySQL DSN 字符串。
   • 返回：匹配的数据库名称列表。

2. list_table

   • 列出 MySQL 服务中的所有表。
   • 参数：
     • dsn（可选）：用于覆盖配置的 MySQL DSN 字符串。
   • 返回：匹配的表名称列表。

3. create_table（只读模式下不可用）

   • 在 MySQL 服务中创建新表。
   • 参数：
     • query：用于创建表的 SQL 查询。
     • dsn（可选）：用于覆盖配置的 MySQL DSN 字符串。
   • 返回：影响的行数。

4. alter_table（只读模式下不可用）

   • 修改 MySQL 服务中的现有表。系统会告知大模型不要删除现有表或列。
   • 参数：
     • query：用于修改表的 SQL 查询。
     • dsn（可选）：用于覆盖配置的 MySQL DSN 字符串。
   • 返回：影响的行数。

5. desc_table

   • 描述表的结构。
   • 参数：
     • name：要描述的表的名称。
     • dsn（可选）：用于覆盖配置的 MySQL DSN 字符串。
   • 返回：表的结构。

数据工具

1. read_query

   • 执行只读 SQL 查询。
   • 参数：
     • query：要执行的 SQL 查询。
     • dsn（可选）：用于覆盖配置的 MySQL DSN 字符串。
   • 返回：查询结果。

2. write_query（只读模式下不可用）

   • 执行写入 SQL 查询。
   • 参数：
     • query：要执行的 SQL 查询。
     • dsn（可选）：用于覆盖配置的 MySQL DSN 字符串。
   • 返回：影响的行数，最后插入的 ID：<last_insert_id>。

3. update_query（只读模式下不可用）

   • 执行更新 SQL 查询。
   • 参数：
     • query：要执行的 SQL 查询。
     • dsn（可选）：用于覆盖配置的 MySQL DSN 字符串。
   • 返回：影响的行数。

4. delete_query（只读模式下不可用）

   • 执行删除 SQL 查询。
   • 参数：
     • query：要执行的 SQL 查询。
     • dsn（可选）：用于覆盖配置的 MySQL DSN 字符串。
   • 返回：影响的行数。

MySQL DSN 格式

dsn 参数或 mysql.dsn 配置选项可以使用以下两种格式：

1. 原生 MySQL DSN 格式

[username[:password]@][protocol[(address)]]/dbname[?param1=value1&...&paramN=valueN]

示例：username:password@tcp(localhost:3306)/mydb?parseTime=true&loc=Local

有关此格式的更多详情，请参阅 MySQL DSN。

2. URL 样式连接格式

mysql://username:password@hostname:port/dbname?param1=value1&param2=value2

示例：mysql://root:pass@localhost:3306/mydb?parseTime=true&loc=Local

此 URL 样式格式会自动转换为原生 MySQL DSN 格式。 支持的 URL 方案包括：mysql://、mariadb://。

命令行参数

启动服务时，可以指定各种设置：

./bin/mcp-mysql server [options]

选项：

• --config、-c：配置文件的路径（默认值："config.yml"）。

贡献

欢迎贡献！请 fork 此仓库，并提交 pull request 来改进项目或修复错误。对于重大更改，请先提出 issue 讨论你的想法。

许可证

本项目采用 MIT License 授权。

作者：cnosuke（x.com/cnosuke）