基于 NodeJS 的 MySQL MCP 服务器

一个提供 MySQL 数据库访问的模型上下文协议服务器。该服务器使 LLM 能够检查数据库模式并执行 SQL 查询。

要求

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

安装

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

Cursor

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

访问 https://smithery.ai/server/@benborla29/mcp-server-mysql
按照 Cursor 的说明操作

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

使用 NPM/PNPM

手动安装：

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

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

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

从本地仓库运行

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

克隆仓库

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

安装依赖
```
npm install
# 或者
pnpm install
```
构建项目
```
npm run build
# 或者
pnpm run build
```

配置 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 凭据以匹配您的环境

测试服务器
```
# 直接运行服务器进行测试
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
        "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_SOCKET_PATH：unix套接字路径的本地连接（例如，“/tmp/mysql.sock”）
MYSQL_HOST：mySQL Server主机（默认：“ 127.0.0.1”） - 如果设置了MySQL_Socket_path，则忽略
MYSQL_PORT：mySQL Server端口（默认：“ 3306”） - 如果设置了mysql_socket_path，则忽略
MYSQL_USER：mySQL用户名（默认：“ root”）
MYSQL_PASS：mySQL密码
MYSQL_DB：目标数据库名称（多DB模式留空）

性能配置

MYSQL_POOL_SIZE：连接池大小（默认：“ 10”）
MYSQL_QUERY_TIMEOUT：查询毫秒的超时（默认值：“ 30000”）
MYSQL_CACHE_TTL：CACHE在毫秒中延续的时间（默认值：“ 60000”）

安全配置

MYSQL_RATE_LIMIT：每分钟的最大查询（默认值：“ 100”）
MYSQL_MAX_QUERY_COMPLEXITY：最大查询复杂度得分（默认值：“ 1000”）
MYSQL_SSL：启用SSL/TLS加密（默认：“ false”）
ALLOW_INSERT_OPERATION：启用插入操作（默认：“ false”）
ALLOW_UPDATE_OPERATION：启用更新操作（默认：“ false”）
ALLOW_DELETE_OPERATION：启用删除操作（默认：“ false”）
ALLOW_DDL_OPERATION：启用DDL操作（默认：“ false”）
SCHEMA_INSERT_PERMISSIONS：架构特定的插入权限
SCHEMA_UPDATE_PERMISSIONS：特定模式的更新权限
SCHEMA_DELETE_PERMISSIONS：特定模式的删除权限
SCHEMA_DDL_PERMISSIONS：架构特异性DDL权限
MULTI_DB_WRITE_MODE：以多DB模式启用写操作（默认值：“ false”）

监视配置

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

多DB模式

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

启用多DB模式

要启用多DB模式，只需离开MYSQL_DB环境变量空。在多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.

测试

数据库设置

在运行测试之前，您需要设置测试数据库并用测试数据播种：

创建测试数据库和用户

-- 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;

运行数据库设置脚本

# Run the database setup script
pnpm run setup:test:db

这将创建必要的表格和种子数据。该脚本位于scripts/setup-test-db.ts

配置测试环境
创建一个.env.test在项目root（如果不存在的话）中文件：

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

更新软件包。JSON脚本
将这些脚本添加到您的软件包。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

正在运行评估

EVALS软件包加载MCP客户端，然后运行index.ts文件，因此无需在测试之间重建。您可以通过前缀NPX命令加载环境变量。可以找到完整的文档here.

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

故障排除

常见问题

连接问题
- 验证MySQL Server正在运行和可访问
- 检查凭据和权限
- 确保启用SSL/TLS配置是正确的
- 尝试与MySQL客户端连接以确认访问
性能问题
- 调整连接池尺寸
- 配置查询超时值
- 如果需要，启用查询缓存
- 检查查询复杂性设置
- 监视服务器资源使用情况
安全限制
- 审查率限制配置
- 检查查询白名单/黑名单设置
- 验证SSL/TLS设置
- 确保用户具有适当的MySQL权限
路径分辨率
如果遇到错误“无法连接到MCP Server MCP-Server-Mysql”，请明确设置所有必需的二进制文件的路径：

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

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

对于路径

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

对于node_path

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

Claude桌面特定问题

如果您在Claude Desktop中看到“服务器断开”日志，请检查~/Library/Logs/Claude/mcp-server-mcp_server_mysql.log
确保您使用节点二进制和服务器脚本的绝对路径
检查您是否.env文件已正确加载；在配置中使用明确的环境变量
尝试直接从命令行运行服务器，以查看是否存在连接问题

如果您需要写操作（插入，更新，删除），请在配置中设置适当的标志为“ true”：

"env": {
  "ALLOW_INSERT_OPERATION": "true",  // Enable INSERT operations
  "ALLOW_UPDATE_OPERATION": "true",  // Enable UPDATE operations
  "ALLOW_DELETE_OPERATION": "true"   // Enable DELETE operations
}

确保您的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"
      }
    }
  }
}

身份验证问题
- 对于MySQL 8.0+，请确保服务器支持caching_sha2_password身份验证插件
- 检查您的MySQL用户是否使用正确的身份验证方法配置
- 如果需要，请尝试使用Legacy身份验证创建用户：
```
CREATE USER 'user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';
```

@lizhuangs

我正在遇到Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'dotenv' imported from错误
尝试此解决方法：

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

感谢@lizhuangs

贡献

欢迎捐款！请随时提交拉动请求
https://github.com/benborla/mcp-server-mysql

非常感谢以下贡献者：

开发设置

克隆存储库
安装依赖项：pnpm install
建立项目：pnpm run build
运行测试：pnpm test

项目路线图

我们正在积极地增强此MCP服务器。检查我们的CHANGELOG.md有关计划功能的详细信息，包括：

用准备好的语句增强了查询功能
高级安全功能
性能优化
全面的监视
扩展的模式信息

如果您想为任何这些领域做出贡献，请检查Github上的问题或打开新问题以讨论您的想法。

提交更改

分叉存储库
创建一个功能分支：git checkout -b feature/your-feature-name
提交您的更改：git commit -am 'Add some feature'
推到分支：git push origin feature/your-feature-name
提交拉请请求

许可证

该MCP服务器已获得MIT许可证的许可。有关详细信息，请参见许可证文件。