星战科技xingzhan.cloud
返回市场
MCP服务器MySQL

MCP服务器MySQL

作者：benborla933 星标更新：2025-11-18
安装使用来源：spider==github.com

项目介绍

基于NodeJS的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数据库访问的模型上下文协议服务器。此服务器使Claude和其他LLMs能够安全地检查数据库模式并执行SQL查询。

目录

需求

  • 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服务器的集中注册表，并简化了安装过程。

Claude Code

选项1：从Claude桌面导入（如果已配置则推荐）

如果您已经在Claude桌面中配置了此MCP服务器，您可以自动导入它：

claude mcp add-from-claude-desktop

这将显示一个交互式对话框，您可以从中选择要导入的mcp_server_mysql服务器及其所有现有配置。

选项2：手动配置

使用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桌面

    将以下内容添加到您的Claude桌面配置文件（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桌面一起使用。

在远程模式下运行

要在远程模式下运行，您需要向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查询
    • 默认情况下，仅限于只读操作
    • 可选写操作（当通过配置启用时）：
      • 插入：向表中添加新数据（需要ALLOW_INSERT_OPERATION=true）
      • 更新：修改现有数据（需要ALLOW_UPDATE_OPERATION=true）
      • 删除：删除数据（需要ALLOW_DELETE_OPERATION=true）
    • 所有操作都在事务中执行，并具有适当的提交/回滚处理
    • 支持预编译语句以安全处理参数
    • 可配置的查询超时和结果分页
    • 内置的查询执行统计信息

资源

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

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

安全特性

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

性能优化

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

监控和调试

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

配置

使用Smithery自动配置

如果您使用Smithery安装，您的配置已经设置好。您可以使用以下命令查看或修改配置：

smithery configure @benborla29/mcp-server-mysql

重新配置时，您可以更新任何MySQL连接细节以及写操作设置：

  • 基本连接设置：

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

  • 写操作权限：

    • 允许插入操作：设置为true以允许添加新数据
    • 允许更新操作：设置为true以允许更新现有数据
    • 允许删除操作：设置为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": "11000",
        "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时，它将优先于单独的连接设置。这对于以下情况特别有用：

  • 频繁过期的凭据轮换
  • 临时数据库连接
  • 使用不同数据库