m

mcp-MySQL只读服务器

@benborla/mcp-server-mysql
1 Stars 565 次浏览 benborla 更新于 2026-08-23

一种提供对MySQL数据库只读访问的模型上下文协议服务器，使大型语言模型能够检查数据库模式并执行只读查询。

开发者工具

MCP 服务配置

复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用

{
  "mcpServers": {
    "MySQL": {
      "args": [
        "mcprunner",
        "MYSQL_HOST=127.0.0.1",
        "MYSQL_PORT=3306",
        "MYSQL_USER=root",
        "MYSQL_PASS=root",
        "MYSQL_DB=demostore",
        "ALLOW_INSERT_OPERATION=true",
        "ALLOW_UPDATE_OPERATION=true",
        "ALLOW_DELETE_OPERATION=false",
        "--",
        "npx",
        "-y",
        "@benborla29/mcp-server-mysql"
      ],
      "command": "npx"
    }
  }
}

该服务需要配置环境变量：MYSQL_DB、MYSQL_HOST、MYSQL_PASS、MYSQL_PORT、MYSQL_USER、PATH

服务介绍

基于 NodeJS 的 MySQL MCP 服务器

smithery 徽章

演示

这是一个提供访问 MySQL 数据库的模型上下文协议（MCP）服务器。该服务器使大型语言模型能够检查数据库模式并执行 SQL 查询。

目录

要求

  • Node.js v18 或更高版本
  • MySQL 5.7 或更高版本（推荐 MySQL 8.0+）
  • 具有适当权限的 MySQL 用户，以执行你需要的操作
  • 对于写操作：具有 INSERT、UPDATE 和/或 DELETE 权限的 MySQL 用户

安装

有多种方法可以安装和配置 MCP 服务器：

Claude 桌面版

要为 Claude 桌面应用程序手动配置 MCP 服务器，请在你的 claude_desktop_config.json 文件中添加以下内容（通常位于用户目录中）：

{
  "mcpServers": {
    "mcp_server_mysql": {
      "command": "npx",
      "args": [
        "-y",
        "@benborla29/mcp-server-mysql"
      ],
      "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": "/Users/atlasborla/Library/Application Support/Herd/config/nvm/versions/node/v22.9.0/bin:/usr/bin:/bin", // <--- Important to add the following, run in your terminal `echo "$(which node)/../"` to get the path
           "NODE_PATH": "/Users/atlasborla/Library/Application Support/Herd/config/nvm/versions/node/v22.9.0/lib/node_modules" // <--- Important to add the following, run in your terminal `echo "$(which node)/../../lib/node_modules"`
      }
    }
  }
}

Cursor

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

npx mcprunner MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_USER=root MYSQL_PASS=root MYSQL_DB=demostore ALLOW_INSERT_OPERATION=true ALLOW_UPDATE_OPERATION=true ALLOW_DELETE_OPERATION=false -- npx -y @benborla29/mcp-server-mysql

别忘了替换该命令中的 env 值。如果你使用的是最新版本（v0.47 及以上）的 Cursor，只需复制并粘贴下面的配置即可：

mcp.json

{
  "mcpServers": {
    "MySQL": {
      "command": "npx",
      "args": [
        "mcprunner",
        "MYSQL_HOST=127.0.0.1",
        "MYSQL_PORT=3306",
        "MYSQL_USER=root",
        "MYSQL_PASS=root",
        "MYSQL_DB=demostore",
        "ALLOW_INSERT_OPERATION=true",
        "ALLOW_UPDATE_OPERATION=true",
        "ALLOW_DELETE_OPERATION=false",
        "--",
        "npx",
        "-y",
        "@benborla29/mcp-server-mysql"
      ]
    }
  }
}

使用 Smithery

通过 Smithery 安装和配置此 MCP 服务器是最简单的方法：

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

在配置过程中，系统将提示你输入 MySQL 连接详细信息。Smithery 将自动：

  • 设置正确的环境变量
  • 配置你的 LLM 应用程序以使用 MCP 服务器
  • 测试与你的 MySQL 数据库的连接
  • 在需要时提供有用的故障排除
  • 配置写操作设置（INSERT、UPDATE、DELETE 权限）

安装将询问以下连接详细信息：

  • MySQL 主机（默认：127.0.0.1）
  • MySQL 端口（默认：3306）
  • MySQL 用户名
  • MySQL 密码
  • MySQL 数据库名称
  • SSL 配置（如果需要）
  • 写操作权限：
    • 允许 INSERT 操作（默认：false）
    • 允许 UPDATE 操作（默认：false）
    • 允许 DELETE 操作（默认：false）

出于安全原因，默认情况下禁用写操作。仅在需要 Claude 修改数据库数据时启用它们。

使用 MCP Get

你也可以使用 MCP Get 安装此包：

npx @michaellatman/mcp-get@latest install @benborla29/mcp-server-mysql

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

使用 NPM/PNPM

对于手动安装：

# Using npm
npm install -g @benborla29/mcp-server-mysql

# Using 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": "/Users/atlasborla/Library/Application Support/Herd/config/nvm/versions/node/v22.9.0/bin:/usr/bin:/bin", // <--- 重要：添加以下路径，在终端中运行 `echo "$(which node)/../"` 获取路径
        "NODE_PATH": "/Users/atlasborla/Library/Application Support/Herd/config/nvm/versions/node/v22.9.0/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一起使用了。

组件

工具

  • 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": {
        // Basic connection settings
        "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",
        
        // Performance settings
        "MYSQL_POOL_SIZE": "10",
        "MYSQL_QUERY_TIMEOUT": "30000",
        "MYSQL_CACHE_TTL": "60000",
        
        // Security settings
        "MYSQL_RATE_LIMIT": "100",
        "MYSQL_MAX_QUERY_COMPLEXITY": "1000",
        "MYSQL_SSL": "true",
        
        // Monitoring settings
        "MYSQL_ENABLE_LOGGING": "true",
        "MYSQL_LOG_LEVEL": "info",
        "MYSQL_METRICS_ENABLED": "true",
        
        // Write operation flags
        "ALLOW_INSERT_OPERATION": "false",
        "ALLOW_UPDATE_OPERATION": "false",
        "ALLOW_DELETE_OPERATION": "false"
      }
    }
  }
}

环境变量

基本连接

  • MYSQL_HOST：MySQL 服务器主机（默认："127.0.0.1"）
  • MYSQL_PORT：MySQL 服务器端口（默认："3306"）
  • MYSQL_USER：MySQL 用户名（默认："root"）
  • MYSQL_PASS：MySQL 密码
  • MYSQL_DB：目标数据库名称（留空以启用多数据库模式）

性能配置

  • MYSQL_POOL_SIZE：连接池大小（默认："10"）
  • MYSQL_QUERY_TIMEOUT：查询超时时间（毫秒）（默认："30000"）
  • MYSQL_CACHE_TTL：缓存生存时间（毫秒）（默认："60000"）

安全配置

  • MYSQL_RATE_LIMIT: 每分钟最大查询次数（默认值："100"）
  • MYSQL_MAX_QUERY_COMPLEXITY: 最大查询复杂度分数（默认值："1000"）
  • MYSQL_SSL: 启用 SSL/TLS 加密（默认值："false"）
  • ALLOW_INSERT_OPERATION: 启用 INSERT 操作（默认值："false"）
  • ALLOW_UPDATE_OPERATION: 启用 UPDATE 操作（默认值："false"）
  • ALLOW_DELETE_OPERATION: 启用 DELETE 操作（默认值："false"）
  • ALLOW_DDL_OPERATION: 启用 DDL 操作（默认值："false"）
  • SCHEMA_INSERT_PERMISSIONS: 特定模式的 INSERT 权限
  • SCHEMA_UPDATE_PERMISSIONS: 特定模式的 UPDATE 权限
  • SCHEMA_DELETE_PERMISSIONS: 特定模式的 DELETE 权限
  • SCHEMA_DDL_PERMISSIONS: 特定模式的 DDL 权限
  • MULTI_DB_WRITE_MODE: 在多数据库模式下启用写操作（默认值："false"）

监控配置

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

多数据库模式

当未设置特定数据库时，MCP-Server-MySQL 支持连接到多个数据库。这允许 LLM 查询 MySQL 用户可以访问的任何数据库。详情请参阅 README-MULTI-DB.md。

启用多数据库模式

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

-- Use fully qualified table names
SELECT * FROM database_name.table_name;

-- Or use USE statements to switch between databases
USE database_name;
SELECT * FROM table_name;

特定模式权限

为了对数据库操作进行细粒度控制，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"
  }
}

运行测试

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

# First-time setup
pnpm run setup:test:db

# Run all tests
pnpm test

故障排除

常见问题

  1. 连接问题

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

  2. 性能问题

    • 调整连接池大小
    • 配置查询超时值
    • 根据需要启用查询缓存
    • 检查查询复杂性设置
    • 监控服务器资源使用情况

  3. 安全限制

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

  4. 路径解析
    如果你遇到“Could not connect to MCP server mcp-server-mysql”错误，请显式设置所有必需的二进制文件路径：

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

在哪里可以找到我的 node bin 路径？
运行以下命令来获取它：

对于 PATH

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

对于 NODE_PATH

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

  1. Claude Desktop 特定问题

    • 如果在 Claude Desktop 中看到 "Server disconnected" 日志，请检查 ~/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"
      }
    }
  }
}

  2. 认证问题

    • 对于 MySQL 8.0+，确保服务器支持 caching_sha2_password 认证插件
    • 检查你的 MySQL 用户是否配置了正确的认证方法
    • 如果需要，尝试创建一个使用传统认证的用户： 
      CREATE USER 'user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';
      @lizhuangs

  3. 我遇到了 Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'dotenv' imported from 错误
    尝试这个解决方法：

    #14

    感谢 @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. Fork 仓库
  2. 创建一个特性分支: git checkout -b feature/your-feature-name
  3. 提交你的更改: git commit -am 'Add some feature'
  4. 推送到分支: git push origin feature/your-feature-name
  5. 提交一个拉取请求

许可证

此 MCP 服务器采用 MIT 许可证。详情请参阅 LICENSE 文件。

查看源码 项目主页

相关 MCP 服务

LeetCode(力扣)
jinzcdev/leetcode-mcp-server
MCP 服务器实现 LeetCode API 集成，支持自动化获取编程题库、用户数据和竞赛信息。
可视化图表-MCP-Server
antvis/mcp-server-chart
这是一个基于AntV的模型上下文协议服务器，用于生成图表。它支持超过20种类型的图表，并且可以与多种桌面应用程序和平台一起使用。
微软Playwright
@microsoft/playwright-mcp
一种模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页交互，而无需使用视觉模型或截图。
MCP上下文模型文档
@upstash/context7-mcp
一种模型上下文协议服务器，它从库中直接获取最新、特定版本的文档和代码示例并将其引入LLM提示中，帮助开发人员在无需过时或虚构信息的情况下获得准确的答案。