基于 NodeJS 的 MySQL MCP 服务器

提供对 MySQL 数据库访问的模型上下文协议 (MCP) 服务器。该服务器使 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 IDE，您可以在项目中使用以下命令安装此 MCP 服务器：

1. 访问https://smithery.ai/server/@benborla29/mcp-server-mysql

2. 按照光标的说明进行操作

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

使用 NPM/PNPM

对于手动安装：

手动安装后，您需要配置您的 LLM 应用程序以使用 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 桌面

   将以下内容添加到您的 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 ）

    • 更新：修改现有数据（需要ALLOW_UPDATE_OPERATION=true ）

    • DELETE：删除数据（需要ALLOW_DELETE_OPERATION=true ）

  • 所有操作均在事务内执行，并具有适当的提交/回滚处理

  • 支持准备好的语句以进行安全参数处理

  • 可配置查询超时和结果分页

  • 内置查询执行统计信息

资源

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

• 表模式

  • 每个表的 JSON 架构信息

  • 列名和数据类型

  • 索引信息和约束

  • 外键关系

  • 表统计数据和指标

  • 从数据库元数据中自动发现

安全功能

• 通过准备好的语句预防 SQL 注入

• 查询白名单/黑名单功能

• 查询执行的速率限制

• 查询复杂度分析

• 可配置的连接加密

• 只读事务执行

性能优化

• 优化连接池

• 查询结果缓存

• 大型结果集流

• 查询执行计划分析

• 可配置查询超时

监控和调试

• 全面的查询日志记录

• 性能指标收集

• 错误跟踪和报告

• 健康检查端点

• 查询执行统计信息

配置

使用 Smithery 自动配置

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

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

• 基本连接设置：

  • MySQL 主机、端口、用户、密码、数据库

  • SSL/TLS 配置（如果您的数据库需要安全连接）

• 写操作权限：

  • 允许插入操作：如果要允许添加新数据，则设置为 true

  • 允许更新操作：如果要允许更新现有数据，则设置为 true

  • 允许删除操作：如果要允许删除数据，请设置为 true

出于安全原因，所有写入操作默认禁用。仅当您明确需要 Claude 修改数据库数据时才启用这些设置。

高级配置选项

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

环境变量

基本连接

• 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_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环境变量留空即可。在多数据库模式下，查询需要进行模式限定：

特定于架构的权限

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

配置示例

有关完整详细信息和安全建议，请参阅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" } }

运行测试

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

运行评估

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

故障排除

常见问题

1. 连接问题

   • 验证 MySQL 服务器是否正在运行并且可以访问

   • 检查凭证和权限

   • 如果启用，请确保 SSL/TLS 配置正确

   • 尝试连接 MySQL 客户端以确认访问

2. 性能问题

   • 调整连接池大小

   • 配置查询超时值

   • 如果需要，启用查询缓存

   • 检查查询复杂性设置

   • 监控服务器资源使用情况

3. 安全限制

   • 检查速率限制配置

   • 检查查询白名单/黑名单设置

   • 验证 SSL/TLS 设置

   • 确保用户具有适当的 MySQL 权限

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

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

对于PATH

对于NODE_PATH

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", // 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" } } } }

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请尝试以下解决方法：

感谢@lizhuangs

贡献

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

非常感谢以下贡献者：

开发设置

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 'Add some feature'

4. 推送到分支： git push origin feature/your-feature-name

5. 提交拉取请求

执照

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