基于 NodeJS 的 MySQL MCP 服务器

提供对 MySQL 数据库的只读访问的模型上下文协议 (MCP) 服务器。该服务器使 LLM 能够检查数据库架构并执行只读查询。

安装

使用 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 获取

您也可以使用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 查询
- 所有查询都在只读事务中执行
- 支持准备好的语句以进行安全参数处理
- 可配置查询超时和结果分页
- 内置查询执行统计信息

资源

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

表模式
- 每个表的 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”）

测试

数据库设置

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

创建测试数据库和用户
-- 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文件：
MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_USER=mcp_test MYSQL_PASS=mcp_test_password MYSQL_DB=mcp_test
更新 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

常见问题

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

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

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

贡献

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

开发设置

克隆存储库
安装依赖项： 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 许可证。详情请参阅许可证文件。

MCP Server for MySQL

Integrations