基于 NodeJS 的 MySQL MCP 服务器

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

安装

使用 Smithery

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

# Install the MCP server
npx -y @smithery/cli@latest install @benborla29/mcp-server-mysql --client claude

在配置过程中，系统会提示您输入 MySQL 连接详情。Smithery 将自动：

• 设置正确的环境变量
• 配置您的 LLM 应用程序以使用 MCP 服务器
• 测试到您的 MySQL 数据库的连接
• 如有需要，提供有用的故障排除信息

使用 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 服务器（请参见下面的配置部分）。

组件

工具

• mysql_query
  • 对连接的数据库执行只读 SQL 查询
  • 输入：sql (字符串): 要执行的 SQL 查询
  • 所有查询都在 READ ONLY 事务中执行
  • 支持预处理语句以安全处理参数
  • 可配置的查询超时和结果分页
  • 内置查询执行统计

资源

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

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

安全特性

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

性能优化

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

监控和调试

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

配置

使用 Smithery 自动配置

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

smithery configure @benborla29/mcp-server-mysql

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": "",
        "MYSQL_DB": "db_name"
      }
    }
  }
}

将 db_name 替换为您的数据库名称，或者留空以访问所有数据库。

高级配置选项

为了更精细地控制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"
      }
    }
  }
}

环境变量

基本连接

• 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"）

监控配置

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

测试

数据库设置

在运行测试之前，您需要设置测试数据库并填充测试数据：

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

故障排除

使用Smithery进行故障排除

如果您通过Smithery安装，可以使用其内置诊断工具：

# Check the status of your MCP server
smithery status @benborla29/mcp-server-mysql

# Run diagnostics
smithery diagnose @benborla29/mcp-server-mysql

# View logs
smithery logs @benborla29/mcp-server-mysql

使用MCP Get进行故障排除

如果您通过MCP Get安装：

# Check the status
mcp-get status @benborla29/mcp-server-mysql

# View logs
mcp-get logs @benborla29/mcp-server-mysql

常见问题

希望上述翻译对您有所帮助！如果还有其他部分需要翻译或调整，请告诉我。

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

1. 认证问题
   • 对于 MySQL 8.0+，确保服务器支持 caching_sha2_password 认证插件
   • 检查您的 MySQL 用户是否配置了正确的认证方法
   • 如有需要，尝试创建一个使用旧认证方式的用户：

     CREATE USER 'user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';
     
     

贡献

欢迎贡献！请随时提交 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. 叉仓库
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 文件。