MySQL 的 MCP 服务器 - Claude Code 版

🚀 这是一个针对 Claude Code 优化的修改版本，支持 SSH 隧道
原作者: @benborla29
原始仓库: https://github.com/benborla/mcp-server-mysql
许可证: MIT

基于 NodeJS 的 MySQL 的 MCP 服务器

本分支的主要特性

• ✅ Claude Code 集成 - 针对 Anthropic 的 Claude Code CLI 进行优化
• ✅ SSH 隧道支持 - 内置对远程数据库的 SSH 隧道支持
• ✅ 自动启动/停止钩子 - 与 Claude 的启动/停止功能无缝对接，自动管理隧道
• ✅ DDL 操作支持 - 添加了 MYSQL_DISABLE_READ_ONLY_TRANSACTIONS 环境变量，支持 CREATE TABLE 操作
• ✅ 多项目配置 - 轻松为多个项目配置不同的数据库

Claude Code 用户快速入门

1. 阅读设置指南: 请参阅 PROJECT_SETUP_GUIDE.md，获取详细说明
2. 配置 SSH 隧道: 设置远程数据库的自动 SSH 隧道
3. 与 Claude 配合使用: 集成的 MCP 服务器可与 Claude Code 无缝协作

这是一个通过 SSH 隧道提供 MySQL 数据库访问的 Model Context Protocol 服务器。该服务器使 Claude 及其他大语言模型能够安全地检查数据库模式并执行 SQL 查询。

目录

• 要求
• 安装
  • Smithery
  • 克隆到本地仓库
  • 远程模式
• 组件
• 配置
• 环境变量
• 多数据库模式
• 模式级权限
• 测试
• 故障排除
• 贡献
• 许可证

要求

• Node.js v20 或更高版本
• MySQL 5.7 或更高版本（推荐使用 MySQL 8.0+）
• 具备所需操作权限的 MySQL 用户
• 对于写操作：具备 INSERT、UPDATE 和/或 DELETE 权限的 MySQL 用户

安装

使用 Smithery

有多种方式可以安装和配置 MCP 服务器，但最常见的方式是访问此网站 https://smithery.ai/server/@benborla29/mcp-server-mysql

Cursor

对于 Cursor IDE，您可以在项目中使用以下命令安装此 MCP 服务器：

1. 访问 https://smithery.ai/server/@benborla29/mcp-server-mysql
2. 按照 Cursor 的指示操作

MCP Get 提供了一个集中式的 MCP 服务器注册表，简化了安装流程。

Codex CLI

Codex CLI 的安装方式与 Claude Code 类似：

codex mcp add mcp_server_mysql \
  --env MYSQL_HOST="127.0.0.1" \
  --env MYSQL_PORT="3306" \
  --env MYSQL_USER="root" \
  --env MYSQL_PASS="your_password" \
  --env MYSQL_DB="your_database" \
  --env ALLOW_INSERT_OPERATION="false" \
  --env ALLOW_UPDATE_OPERATION="false" \
  --env ALLOW_DELETE_OPERATION="false" \
  -- npx -y @benborla29/mcp-server-mysql

Claude Code

方法一：从 Claude Desktop 导入（已配置时推荐）

如果您已经在 Claude Desktop 中配置了此 MCP 服务器，可以直接导入：

claude mcp add-from-claude-desktop

这将弹出一个交互式对话框，您可以选择要导入的 mcp_server_mysql 服务器，并保留所有现有配置。

方法二：手动配置

使用 NPM/PNPM 全局安装：

首先，全局安装该包：

# 使用 npm
npm install -g @benborla29/mcp-server-mysql

# 使用 pnpm
pnpm add -g @benborla29/mcp-server-mysql

然后将服务器添加到 Claude Code：

claude mcp add mcp_server_mysql \
  -e MYSQL_HOST="127.0.0.1" \
  -e MYSQL_PORT="3306" \
  -e MYSQL_USER="root" \
  -e MYSQL_PASS="your_password" \
  -e MYSQL_DB="your_database" \
  -e ALLOW_INSERT_OPERATION="false" \
  -e ALLOW_UPDATE_OPERATION="false" \
  -e ALLOW_DELETE_OPERATION="false" \
  -- npx @benborla29/mcp-server-mysql

使用本地仓库（用于开发）：

如果您是从克隆的仓库运行：

claude mcp add mcp_server_mysql \
  -e MYSQL_HOST="127.0.0.1" \
  -e MYSQL_PORT="3306" \
  -e MYSQL_USER="root" \
  -e MYSQL_PASS="your_password" \
  -e MYSQL_DB="your_database" \
  -e ALLOW_INSERT_OPERATION="false" \
  -e ALLOW_UPDATE_OPERATION="false" \
  -e ALLOW_DELETE_OPERATION="false" \
  -e PATH="/path/to/node/bin:/usr/bin:/bin" \
  -e NODE_PATH="/path/to/node/lib/node_modules" \
  -- /path/to/node /full/path/to/mcp-server-mysql/dist/index.js

请替换：

• /path/to/node 为您 Node.js 可执行文件的路径（可通过 which node 查找）
• /full/path/to/mcp-server-mysql 为您的克隆仓库的完整路径
• 更新 MySQL 凭证以匹配您的环境

使用 Unix 套接字连接：

对于使用 Unix 套接字的本地 MySQL 实例：

claude mcp add mcp_server_mysql \
  -e MYSQL_SOCKET_PATH="/tmp/mysql.sock" \
  -e MYSQL_USER="root" \
  -e MYSQL_PASS="your_password" \
  -e MYSQL_DB="your_database" \
  -e ALLOW_INSERT_OPERATION="false" \
  -e ALLOW_UPDATE_OPERATION="false" \
  -e ALLOW_DELETE_OPERATION="false" \
  -- npx @benborla29/mcp-server-mysql

选择合适的范围

根据您的需求选择合适的范围：

# 本地范围（默认）：仅在当前项目中可用
claude mcp add mcp_server_mysql [选项...]

# 用户范围：在所有项目中均可使用
claude mcp add mcp_server_mysql -s user [选项...]

# 项目范围：可通过 .mcp.json 文件与团队成员共享
claude mcp add mcp_server_mysql -s project [选项...]

对于包含凭据的数据库服务器，建议使用 本地 或 用户 范围，以保护凭据的安全性。

验证

添加服务器后，请验证其是否正确配置：

# 列出所有已配置的服务器
claude mcp list

# 获取您的 MySQL 服务器的详细信息
claude mcp get mcp_server_mysql

# 在 Claude Code 中检查服务器状态
/mcp

多数据库配置

对于多数据库模式，省略 MYSQL_DB 环境变量：

claude mcp add mcp_server_mysql_multi \
  -e MYSQL_HOST="127.0.0.1" \
  -e MYSQL_PORT="3306" \
  -e MYSQL_USER="root" \
  -e MYSQL_PASS="your_password" \
  -e MULTI_DB_WRITE_MODE="false" \
  -- npx @benborla29/mcp-server-mysql

高级配置

如需使用高级功能，请添加以下环境变量：

claude mcp add mcp_server_mysql \
  -e MYSQL_HOST="127.0.0.1" \
  -e MYSQL_PORT="3306" \
  -e MYSQL_USER="root" \
  -e MYSQL_PASS="your_password" \
  -e MYSQL_DB="your_database" \
  -e MYSQL_POOL_SIZE="10" \
  -e MYSQL_QUERY_TIMEOUT="30000" \
  -e MYSQL_CACHE_TTL="60000" \
  -e MYSQL_RATE_LIMIT="100" \
  -e MYSQL_SSL="true" \
  -e ALLOW_INSERT_OPERATION="false" \
  -e ALLOW_UPDATE_OPERATION="false" \
  -e ALLOW_DELETE_OPERATION="false" \
  -e MYSQL_ENABLE_LOGGING="true" \
  -- npx @benborla29/mcp-server-mysql

Claude Code 设置故障排除

1. 服务器连接问题：在 Claude Code 中使用 /mcp 命令检查服务器状态，并在必要时进行身份验证。

2. 路径问题：如果使用本地仓库，请确保 Node.js 路径已正确设置：

   # 查找 Node.js 路径
   which node
   
   # 对于 PATH 环境变量
   echo "$(which node)/../"
   
   # 对于 NODE_PATH 环境变量
   echo "$(which node)/../../lib/node_modules"
   

3. 权限错误：请确保您的 MySQL 用户拥有您所启用操作的相应权限。

4. 服务器未启动：检查 Claude Code 日志或直接运行服务器以进行调试：

   # 直接测试服务器
   npx @benborla29/mcp-server-mysql
   

使用 NPM/PNPM

手动安装方法如下：

# 使用 npm
npm install -g @benborla29/mcp-server-mysql

# 使用 pnpm
pnpm add -g @benborla29/mcp-server-mysql

手动安装完成后，您需要配置您的 LLM 应用程序以使用 MCP 服务器（请参阅下方的配置部分）。

从本地仓库运行

如果您希望直接从源代码克隆并运行此 MCP 服务器，请按照以下步骤操作：

1. 克隆仓库

   git clone https://github.com/benborla/mcp-server-mysql.git
   cd mcp-server-mysql
   

2. 安装依赖项

   npm install
   # 或
   pnpm install
   

3. 构建项目

   npm run build
   # 或
   pnpm run build
   

4. 配置 Claude Desktop

   将以下内容添加到您的 Claude Desktop 配置文件 (claude_desktop_config.json) 中：

   {
     "mcpServers": {
       "mcp_server_mysql": {
         "command": "/path/to/node",
         "args": [
           "/full/path/to/mcp-server-mysql/dist/index.js"
         ],
         "env": {
           "MYSQL_HOST": "127.0.0.1",
           "MYSQL_PORT": "3306",
           "MYSQL_USER": "root",
           "MYSQL_PASS": "your_password",
           "MYSQL_DB": "your_database",
           "ALLOW_INSERT_OPERATION": "false",
           "ALLOW_UPDATE_OPERATION": "false",
           "ALLOW_DELETE_OPERATION": "false",
           "PATH": "/path/to/node/bin:/usr/bin:/bin", // <--- 重要：请运行 `echo "$(which node)/../"` 来获取路径
           "NODE_PATH": "/path/to/node/lib/node_modules" // <--- 重要：请运行 `echo "$(which node)/../../lib/node_modules"` 来获取路径
         }
       }
     }
   }
   

   替换：

   • /path/to/node 为您的 Node.js 可执行文件的完整路径（可通过 which node 查找）
   • /full/path/to/mcp-server-mysql 为您克隆仓库的完整路径
   • 根据您的环境设置 MySQL 凭证

5. 测试服务器

   # 直接运行服务器进行测试
   node dist/index.js
   

   如果成功连接到 MySQL，则可以将其与 Claude Desktop 一起使用。

远程模式运行

要在远程模式下运行，您需要向 npx 脚本提供 环境变量。

1. 在首选目录中创建 .env 文件：

   # 创建 .env 文件
   touch .env
   

2. 复制并粘贴此仓库中的 示例文件

3. 根据您的环境设置 MySQL 凭证

4. 设置 IS_REMOTE_MCP=true

5. 设置一个安全的字符串作为 REMOTE_SECRET_KEY

6. 如有需要，可自定义 PORT。默认值为 3000。

7. 在当前会话中加载变量：

   source .env
   

8. 运行服务器：

   npx @benborla29/mcp-server-mysql
   

9. 配置您的代理以通过以下配置连接到 MCP：

   {
     "mcpServers": {
       "mysql": {
         "url": "http://your-host:3000/mcp",
         "type": "streamableHttp",
         "headers": {
           "Authorization": "Bearer <REMOTE_SECRET_KEY>"
         }
       }
     }
   }
   

组件

工具

• mysql_query
  • 对连接的数据库执行 SQL 查询
  • 输入：sql（字符串）：要执行的 SQL 查询
  • 默认情况下，仅限只读操作
  • 可选写入操作（通过配置启用）：
    • INSERT：向表中添加新数据（需设置 ALLOW_INSERT_OPERATION=true）
    • UPDATE：修改现有数据（需设置 ALLOW_UPDATE_OPERATION=true）
    • DELETE：删除数据（需设置 ALLOW_DELETE_OPERATION=true）
  • 所有操作均在事务中执行，并妥善处理提交和回滚
  • 支持预处理语句以安全地处理参数
  • 可配置查询超时时间和结果分页
  • 内置查询执行统计信息

资源

服务器提供全面的数据库信息：

• 表结构
  • 每个表的 JSON 模式信息
  • 列名和数据类型
  • 索引信息和约束条件
  • 外键关系
  • 表统计信息和指标
  • 自动从数据库元数据中发现

安全特性

• 通过预处理语句防止 SQL 注入
• 查询白名单/黑名单功能
• 查询执行速率限制
• 查询复杂度分析
• 可配置的连接加密
• 强制执行只读事务

性能优化

• 优化的连接池
• 查询结果缓存
• 大型结果集流式传输
• 查询执行计划分析
• 可配置的查询超时时间

监控与调试

• 全面的查询日志记录
• 性能指标收集
• 错误跟踪与报告
• 健康检查端点
• 查询执行统计信息

配置

使用 Smithery 自动配置

如果您使用 Smithery 进行安装，您的配置已经设置完毕。您可以通过以下命令查看或修改配置：

smithery configure @benborla29/mcp-server-mysql

在重新配置时，您可以更新 MySQL 的连接信息以及写操作的相关设置：

• 基本连接设置：

  • MySQL 主机、端口、用户名、密码、数据库
  • SSL/TLS 配置（如果您的数据库需要安全连接）

• 写操作权限：

  • 允许 INSERT 操作：如果您希望允许添加新数据，请将其设置为 true
  • 允许 UPDATE 操作：如果您希望允许更新现有数据，请将其设置为 true
  • 允许 DELETE 操作：如果您希望允许删除数据，请将其设置为 true

出于安全考虑，默认情况下所有写操作均被禁用。请仅在您明确需要 Claude 修改数据库数据时才启用这些设置。

高级配置选项

为了更精细地控制 MCP 服务器的行为，您可以使用以下高级配置选项：

{
  "mcpServers": {
    "mcp_server_mysql": {
      "command": "/path/to/npx/binary/npx",
      "args": [
        "-y",
        "@benborla29/mcp-server-mysql"
      ],
      "env": {
        // 基本连接设置
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASS": "",
        "MYSQL_DB": "db_name",
        "PATH": "/path/to/node/bin:/usr/bin:/bin",

        // 性能设置
        "MYSQL_POOL_SIZE": "10",
        "MYSQL_QUERY_TIMEOUT": "30000",
        "MYSQL_CACHE_TTL": "60000",

        // 安全设置
        "MYSQL_RATE_LIMIT": "100",
        "MYSQL_MAX_QUERY_COMPLEXITY": "1000",
        "MYSQL_SSL": "true",

        // 监控设置
        "ENABLE_LOGGING": "true",
        "MYSQL_LOG_LEVEL": "info",
        "MYSQL_METRICS_ENABLED": "true",

        // 写操作标志
        "ALLOW_INSERT_OPERATION": "false",
        "ALLOW_UPDATE_OPERATION": "false",
        "ALLOW_DELETE_OPERATION": "false"
      }
    }
  }
}

环境变量

基本连接

• MYSQL_SOCKET_PATH：用于本地连接的 Unix 套接字路径（例如 "/tmp/mysql.sock"）
• MYSQL_HOST：MySQL 服务器主机（默认值为 127.0.0.1），若设置了 MYSQL_SOCKET_PATH 则忽略此设置
• MYSQL_PORT：MySQL 服务器端口（默认值为 3306），若设置了 MYSQL_SOCKET_PATH 则忽略此设置
• MYSQL_USER：MySQL 用户名（默认值为 root）
• MYSQL_PASS：MySQL 密码
• MYSQL_DB：目标数据库名称（留空则进入多数据库模式）

替代方案：连接字符串

对于需要频繁轮换凭据或临时连接的场景，您可以使用 MySQL 连接字符串代替单独的环境变量：

• MYSQL_CONNECTION_STRING：MySQL CLI 格式的连接字符串（例如 mysql --default-auth=mysql_native_password -A -hHOST -PPORT -uUSER -pPASS database_name）

当提供了 MYSQL_CONNECTION_STRING 时，它将优先于单独的连接设置。这在以下情况下尤为有用：

• 凭据经常过期且需要轮换
• 临时数据库连接
• 快速测试不同的数据库配置

注意：出于安全考虑，此设置应仅通过环境变量进行配置，而不应存储在版本控制的配置文件中。对于会过期的凭据，建议在 Claude Code 的 MCP 配置中使用 prompt 输入类型。

性能配置

• MYSQL_POOL_SIZE：连接池大小（默认值为 10）
• MYSQL_QUERY_TIMEOUT：查询超时时间，单位为毫秒（默认值为 30000）
• MYSQL_CACHE_TTL：缓存存活时间，单位为毫秒（默认值为 60000）
• MYSQL_QUEUE_LIMIT：排队等待的连接请求数量上限（默认值为 100）
• MYSQL_CONNECT_TIMEOUT：连接超时时间，单位为毫秒（默认值为 10000）

安全配置

• MYSQL_RATE_LIMIT：每分钟最大查询次数（默认值为 100）
• MYSQL_MAX_QUERY_COMPLEXITY：最大查询复杂度分数（默认值为 1000）
• MYSQL_SSL：启用 SSL/TLS 加密（默认值为 false）
• MYSQL_SSL_CA：SSL CA 证书文件路径（PEM 格式）。仅在 MYSQL_SSL=true 时使用。连接自签名证书或使用自定义 CA 的 MySQL 实例时必须提供。
• MYSQL_SSL_CERT：客户端证书文件路径（PEM 格式），用于 mTLS。仅在 MYSQL_SSL=true 时使用。启用双向 TLS（mTLS）认证，即服务器和客户端均需出示证书。某些强制验证客户端证书的数据库配置需要此设置。
• MYSQL_SSL_KEY：客户端私钥文件路径（PEM 格式），用于 mTLS。仅在 MYSQL_SSL=true 时使用。必须与 MYSQL_SSL_CERT 中指定的证书相对应。
• ALLOW_INSERT_OPERATION：启用 INSERT 操作（默认值为 false）
• ALLOW_UPDATE_OPERATION：启用 UPDATE 操作（默认值为 false）
• ALLOW_DELETE_OPERATION：启用 DELETE 操作（默认值为 false）
• ALLOW_DDL_OPERATION：启用 DDL 操作（默认值为 false）
• MYSQL_DISABLE_READ_ONLY_TRANSACTIONS：[新增] 禁用只读事务强制执行（默认值为 false）⚠️ 安全警告：仅在您需要完全的写入能力并信任 LLM 可以访问您的数据库时才启用此设置
• SCHEMA_INSERT_PERMISSIONS：针对特定模式的 INSERT 权限
• SCHEMA_UPDATE_PERMISSIONS：针对特定模式的 UPDATE 权限
• SCHEMA_DELETE_PERMISSIONS：针对特定模式的 DELETE 权限
• SCHEMA_DDL_PERMISSIONS：针对特定模式的 DDL 权限
• MULTI_DB_WRITE_MODE：启用多数据库模式下的写操作（默认值为 false）

时区和日期配置

• MYSQL_TIMEZONE：设置日期/时间值的时区。支持的格式包括 +08:00（UTC+8）、-05:00（UTC-5）、Z（UTC）或 local（系统时区）。有助于确保在不同服务器位置之间保持一致的日期/时间处理。
• MYSQL_DATE_STRINGS：当设置为 "true"时，日期/时间值将以字符串形式返回，而不是 JavaScript Date 对象。这样可以保留数据库中的精确值，而不会进行任何时区转换，特别适用于：
  • 需要精确控制日期格式的应用程序
  • 跨时区的数据库操作
  • 避免 JavaScript Date 的时区问题

监控配置

• MYSQL_ENABLE_LOGGING：启用查询日志记录（默认值为 false）
• MYSQL_LOG_LEVEL：日志级别（默认值为 info）
• MYSQL_METRICS_ENABLED：启用性能指标（默认值为 false）

远程 MCP 配置

• IS_REMOTE_MCP：启用远程 MCP 模式（默认值为 false）
• REMOTE_SECRET_KEY：用于远程 MCP 认证的密钥（默认值为空）。若未提供，则远程 MCP 模式将被禁用。
• PORT：远程 MCP 服务器的端口号（默认值为 3000）

多数据库模式

MCP-Server-MySQL 支持在未指定具体数据库的情况下连接多个数据库。这使得 LLM 可以查询 MySQL 用户有权访问的任意数据库。有关详细信息，请参阅 README-MULTI-DB.md。

启用多数据库模式

要启用多数据库模式，只需将 MYSQL_DB 环境变量留空。在多数据库模式下，查询需要指定模式：

-- 使用完全限定的表名
SELECT * FROM 数据库名.表名;

-- 或者使用 USE 语句切换数据库
USE 数据库名;
SELECT * FROM 表名;

模式特定的权限

为了对数据库操作进行细粒度控制，MCP-Server-MySQL 现在支持模式特定的权限。这允许不同的数据库拥有不同的访问级别（只读、读写等）。

配置示例

SCHEMA_INSERT_PERMISSIONS=development:true,test:true,production:false
SCHEMA_UPDATE_PERMISSIONS=development:true,test:true,production:false
SCHEMA_DELETE_PERMISSIONS=development:false,test:true,production:false
SCHEMA_DDL_PERMISSIONS=development:false,test:true,production:false

有关完整详情和安全建议，请参阅 README-MULTI-DB.md。

测试

数据库设置

在运行测试之前，您需要设置测试数据库并填充测试数据：

1. 创建测试数据库和用户

   -- 以 root 用户身份连接并创建测试数据库
   CREATE DATABASE IF NOT EXISTS mcp_test;
   
   -- 创建具有适当权限的测试用户
   CREATE USER IF NOT EXISTS 'mcp_test'@'localhost' IDENTIFIED BY 'mcp_test_password';
   GRANT ALL PRIVILEGES ON mcp_test.* TO 'mcp_test'@'localhost';
   FLUSH PRIVILEGES;
   

2. 运行数据库设置脚本

   # 运行数据库设置脚本
   pnpm run setup:test:db
   

   这将创建必要的表并填充数据。该脚本位于 scripts/setup-test-db.ts 中。

3. 配置测试环境 在项目根目录中创建 .env.test 文件（如果尚未存在）：

   MYSQL_HOST=127.0.0.1
   MYSQL_PORT=3306
   MYSQL_USER=mcp_test
   MYSQL_PASS=mcp_test_password
   MYSQL_DB=mcp_test
   

4. 更新 package.json 脚本 将以下脚本添加到您的 package.json 中：

   {
     "scripts": {
       "setup:test:db": "ts-node scripts/setup-test-db.ts",
       "pretest": "pnpm run setup:test:db",
       "test": "vitest run",
       "test:watch": "vitest",
       "test:coverage": "vitest run --coverage"
     }
   }
   

运行测试

该项目包含一个全面的测试套件，以确保功能性和可靠性：

# 首次设置
pnpm run setup:test:db

# 运行所有测试
pnpm test

运行 evals

evals 包加载了一个 mcp 客户端，然后运行 index.ts 文件，因此无需在每次测试之间重新构建。您可以通过在 npx 命令前添加环境变量来加载它们。完整的文档可在 MCP Evals 上找到。

OPENAI_API_KEY=your-key  npx mcp-eval evals.ts index.ts

故障排除

常见问题

1. 连接问题

   • 确认 MySQL 服务器正在运行且可访问。
   • 检查凭据和权限。
   • 如果启用了 SSL/TLS，请确保配置正确。
   • 尝试使用 MySQL 客户端连接以确认访问权限。

2. 性能问题

   • 调整连接池大小。
   • 配置查询超时值。
   • 如有必要，启用查询缓存。
   • 检查查询复杂度设置。
   • 监控服务器资源使用情况。

3. 安全限制

   • 检查速率限制配置。
   • 查看查询白名单/黑名单设置。
   • 验证 SSL/TLS 设置。
   • 确保用户具有适当的 MySQL 权限。

4. 路径解析问题 如果遇到“无法连接到 MCP 服务器 mcp-server-mysql”的错误，请显式设置所有所需二进制文件的路径：

   {
     "env": {
       "PATH": "/path/to/node/bin:/usr/bin:/bin"
     }
   }
   

   如何找到我的 node 二进制文件路径？ 运行以下命令获取：

   对于 PATH：

   echo "$(which node)/../"
   

   对于 NODE_PATH：

   echo "$(which node)/../../lib/node_modules"
   

5. Claude Desktop 特定问题

   • 如果在 Claude Desktop 中看到“服务器断开连接”的日志，请检查 ~/Library/Logs/Claude/mcp-server-mcp_server_mysql.log 中的日志。

   • 确保您使用的是 Node 二进制文件和服务器脚本的绝对路径。

   • 检查 .env 文件是否被正确加载；在配置中使用显式环境变量。

   • 尝试直接从命令行运行服务器，以查看是否存在连接问题。

   • 如果需要写操作（INSERT、UPDATE、DELETE），请在配置中将相应标志设置为“true”：

     "env": {
       "ALLOW_INSERT_OPERATION": "true",  // 启用 INSERT 操作
       "ALLOW_UPDATE_OPERATION": "true",  // 启用 UPDATE 操作
       "ALLOW_DELETE_OPERATION": "true"   // 启用 DELETE 操作
     }
     

   • 确保您的 MySQL 用户具有您所启用操作的适当权限。

   • 对于直接执行的配置，使用：

     {
       "mcpServers": {
         "mcp_server_mysql": {
           "command": "/full/path/to/node",
           "args": [
             "/full/path/to/mcp-server-mysql/dist/index.js"
           ],
           "env": {
             "MYSQL_HOST": "127.0.0.1",
             "MYSQL_PORT": "3306",
             "MYSQL_USER": "root",
             "MYSQL_PASS": "your_password",
             "MYSQL_DB": "your_database"
           }
         }
       }
     }
     

6. 认证问题

   • 对于 MySQL 8.0+，请确保服务器支持 caching_sha2_password 认证插件。

   • 检查您的 MySQL 用户是否配置了正确的认证方法。

   • 如有必要，尝试创建使用旧版认证的用户：

     CREATE USER 'user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';
     

     @lizhuangs

7. 我遇到了 Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'dotenv' imported from 错误， 可以尝试以下解决方法：

   npx -y -p @benborla29/mcp-server-mysql -p dotenv mcp-server-mysql
   

   感谢 @lizhuangs。

贡献

欢迎贡献！请随时提交 Pull Request 到 https://github.com/benborla/mcp-server-mysql

非常感谢以下贡献者

开发设置

1. 克隆仓库。
2. 安装依赖：pnpm install。
3. 构建项目：pnpm run build。
4. 运行测试：pnpm test。

项目路线图

我们正在积极开发并优化这款 MCP 服务器。请查看我们的 CHANGELOG.md，了解计划中的功能详情，包括：

• 使用预处理语句增强查询能力
• 高级安全特性
• 性能优化
• 全面的监控功能
• 扩展的模式信息

如果您希望在这些方面做出贡献，请查看 GitHub 上的相关议题，或新建一个议题来讨论您的想法。

提交更改

1. 分支仓库
2. 创建功能分支：git checkout -b feature/your-feature-name
3. 提交更改：git commit -am '添加某项功能'
4. 推送至分支：git push origin feature/your-feature-name
5. 提交拉取请求

许可证

本 MCP 服务器采用 MIT 许可证授权。详细信息请参阅 LICENSE 文件。

mcp-server-mysql 快速上手指南

本指南介绍如何为 Claude Code 配置优化版的 MySQL MCP Server，支持 SSH 隧道连接远程数据库及安全的 SQL 查询执行。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: v20 或更高版本
• MySQL: 5.7 或更高版本（推荐 8.0+）
• 数据库权限:
  • 基础读取：需具备 SELECT 权限
  • 写入操作：需额外具备 INSERT, UPDATE, DELETE 权限（需在配置中显式开启）

安装步骤

方式一：通过 Claude Code CLI 直接安装（推荐）

这是最快捷的方式，适用于全局使用。

1. 全局安装包（可选，CLI 通常会自动处理，但预先安装更稳定）：

   npm install -g @benborla29/mcp-server-mysql
   # 或者使用 pnpm
   pnpm add -g @benborla29/mcp-server-mysql
   

2. 添加服务器到 Claude Code： 运行以下命令，将 MySQL 连接信息注册到 Claude Code。请替换 <your_...> 占位符为您的实际数据库信息。

   claude mcp add mcp_server_mysql \
     -e MYSQL_HOST="127.0.0.1" \
     -e MYSQL_PORT="3306" \
     -e MYSQL_USER="root" \
     -e MYSQL_PASS="your_password" \
     -e MYSQL_DB="your_database" \
     -e ALLOW_INSERT_OPERATION="false" \
     -e ALLOW_UPDATE_OPERATION="false" \
     -e ALLOW_DELETE_OPERATION="false" \
     -- npx @benborla29/mcp-server-mysql
   

   安全提示：默认情况下写操作（INSERT/UPDATE/DELETE）是禁用的。如需开启，请将对应环境变量设为 "true"。建议生产环境仅开启读权限。

3. 选择作用域（可选）：

   • 本地项目专用（默认，推荐用于保护凭证）：无需额外参数。
   • 用户全局可用：添加 -s user 参数。
   • 团队项目共享：添加 -s project 参数（凭证会写入 .mcp.json，请注意保密）。

方式二：本地源码运行（开发调试用）

如果您需要修改源码或使用本地克隆版本：

1. 克隆并构建项目：

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

2. 获取 Node 路径： 在终端执行以下命令获取路径，后续配置需要用到：

   which node
   echo "$(which node)/../"
   echo "$(which node)/../../lib/node_modules"
   

3. 配置 Claude Desktop/Code： 编辑配置文件，填入绝对路径和环境变量：

   {
     "mcpServers": {
       "mcp_server_mysql": {
         "command": "/path/to/node",
         "args": [
           "/full/path/to/mcp-server-mysql/dist/index.js"
         ],
         "env": {
           "MYSQL_HOST": "127.0.0.1",
           "MYSQL_PORT": "3306",
           "MYSQL_USER": "root",
           "MYSQL_PASS": "your_password",
           "MYSQL_DB": "your_database",
           "ALLOW_INSERT_OPERATION": "false",
           "ALLOW_UPDATE_OPERATION": "false",
           "ALLOW_DELETE_OPERATION": "false",
           "PATH": "/path/to/node/bin:/usr/bin:/bin",
           "NODE_PATH": "/path/to/node/lib/node_modules"
         }
       }
     }
   }
   

特殊场景配置

• SSH 隧道连接：此版本内置支持 SSH 隧道。若需连接远程内网数据库，请在上述环境变量中增加 SSH 相关配置（参考项目详细文档 PROJECT_SETUP_GUIDE.md），工具会自动管理隧道的启动与停止。
• Unix Socket 连接：如果是本地 MySQL 且使用 Socket 文件：

  claude mcp add mcp_server_mysql \
    -e MYSQL_SOCKET_PATH="/tmp/mysql.sock" \
    -e MYSQL_USER="root" \
    -e MYSQL_PASS="your_password" \
    -e MYSQL_DB="your_database" \
    -- npx @benborla29/mcp-server-mysql
  

• 多数据库模式：如果不指定 MYSQL_DB，可进入多库模式，允许在对话中切换数据库：

  claude mcp add mcp_server_mysql_multi \
    -e MYSQL_HOST="127.0.0.1" \
    -e MYSQL_USER="root" \
    -e MYSQL_PASS="your_password" \
    -e MULTI_DB_WRITE_MODE="false" \
    -- npx @benborla29/mcp-server-mysql
  

基本使用

配置完成后，重启 Claude Code 或在对话中输入 /mcp 检查服务器状态。

1. 验证连接

在 Claude Code 对话框中输入：

"检查 MySQL 连接状态，列出当前数据库的所有表。"

如果配置正确，Claude 将调用 mysql_query 工具返回表结构信息。

2. 执行查询（只读）

默认模式下仅允许读取操作：

"查询 users 表中最近注册的 5 个用户。"

3. 执行写入操作（需配置开启）

如果您在安装时设置了 ALLOW_INSERT_OPERATION="true" 等参数：

"向 logs 表中插入一条新的测试记录。"

4. 查看架构

"分析 orders 表的 schema 结构，并解释每个字段的含义。"

该工具会自动处理事务提交/回滚，并支持预处理语句以确保安全性。