MCP Server for MySQL based on NodeJS

基于 NodeJS 的 MySQL MCP 服务

一个用于访问 MySQL 数据库的 Model Context Protocol 服务。此服务支持大模型检查数据库架构并执行 SQL 查询。

目录

• 要求
• 安装
  • Claude Desktop
  • Cursor
  • Smithery
  • MCP Get
  • 克隆到本地仓库
• 组件
• 配置
• 环境变量
• 多数据库模式
• 特定架构的权限
• 测试
• 故障排除
• 贡献
• 许可证

要求

• Node.js v18 或更高版本
• MySQL 5.7 或更高版本（推荐 MySQL 8.0+）
• 拥有执行所需操作的相应权限的 MySQL 用户
• 对于写入操作：拥有 INSERT、UPDATE 和/或 DELETE 权限的 MySQL 用户

安装

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

Claude Desktop

若要为 Claude Desktop App 手动配置 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 值。如果你使用的是最新版本的 Cursor（v0.47 及以上），只需复制并粘贴以下配置：

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 将自动：

• 设置正确的环境变量
• 配置你的大模型应用以使用 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

手动安装后，你需要配置大模型应用以使用 MCP 服务（见下文的配置部分）。

从本地仓库运行

如果你想直接从源代码克隆并运行此 MCP 服务，请按以下步骤操作：

1. 克隆仓库

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

2. 安装依赖项

   npm install
   # or
   pnpm install
   

3. 构建项目

   npm run build
   # or
   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", // <--- 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"`
         }
       }
     }
   }
   

   替换：

   • 将 /path/to/node 替换为 Node.js 二进制文件的完整路径（运行 which node 查找）
   • 将 /full/path/to/mcp-server-mysql 替换为克隆仓库所在位置的完整路径
   • 设置与你的环境相匹配的 MySQL 凭据

5. 测试服务

   # Run the server directly to test
   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. 创建测试数据库和用户

   -- Connect as root and create test database
   CREATE DATABASE IF NOT EXISTS mcp_test;
   
   -- Create test user with appropriate permissions
   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. 运行数据库设置脚本

   # Run the database setup script
   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 二进制文件的路径 运行以下命令即可获取：

对于 PATH

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

对于 NODE_PATH

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

5. 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"
           }
         }
       }
     }
     

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 上的 issue，或新建一个 issue 来讨论你的想法。

提交更改

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. 提交 Pull Request

许可证

此 MCP 服务基于 MIT License 许可。详情请参阅 LICENSE 文件。