MCP 服务器

MCP Server for MySQL based on NodeJS

镜子 (jìng zi)

MCP-Mirror

开发者工具

访问服务器

README

基于 NodeJS 的 MySQL MCP 服务器

Demo

一个模型上下文协议 (Model Context Protocol, MCP) 服务器，提供对 MySQL 数据库的只读访问。此服务器使 LLM 能够检查数据库模式并执行只读查询。

安装

使用 Smithery

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

# 安装 MCP 服务器
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

对于手动安装：

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

# 使用 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 Desktop App 的手动配置

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

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

高级配置选项

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

{
  "mcpServers": {
    "mcp_server_mysql": {
      "command": "/path/to/npx/binary/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",
        "PATH": "/path/to/node/bin:/usr/bin:/bin",
        
        // 性能设置
        "MYSQL_POOL_SIZE": "10",
        "MYSQL_QUERY_TIMEOUT": "30000",
        "MYSQL_CACHE_TTL": "60000",
        
        // 安全设置
        "MYSQL_RATE_LIMIT": "100",
        "MYSQL_MAX_QUERY_COMPLEXITY": "1000",
        "MYSQL_SSL": "true",
        
        // 监控设置
        "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")

测试

数据库设置

在运行测试之前，您需要设置测试数据库并使用测试数据对其进行种子填充：

创建测试数据库和用户

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

运行数据库设置脚本
```
# 运行数据库设置脚本
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"
  }
}

运行测试

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

# 首次设置
pnpm run setup:test:db

# 运行所有测试
pnpm test

故障排除

使用 Smithery 进行故障排除

如果您使用 Smithery 安装，则可以使用其内置诊断功能：

# 检查您的 MCP 服务器的状态
smithery status @benborla29/mcp-server-mysql

# 运行诊断
smithery diagnose @benborla29/mcp-server-mysql

# 查看日志
smithery logs @benborla29/mcp-server-mysql

使用 MCP Get 进行故障排除

如果您使用 MCP Get 安装：

# 检查状态
mcp-get status @benborla29/mcp-server-mysql

# 查看日志
mcp-get logs @benborla29/mcp-server-mysql

常见问题

连接问题
- 验证 MySQL 服务器是否正在运行且可访问
- 检查凭据和权限
- 确保 SSL/TLS 配置正确（如果已启用）
- 尝试使用 MySQL 客户端连接以确认访问
性能问题
- 调整连接池大小
- 配置查询超时值
- 如果需要，启用查询缓存
- 检查查询复杂性设置
- 监控服务器资源使用情况
安全限制
- 检查速率限制配置
- 检查查询白名单/黑名单设置
- 验证 SSL/TLS 设置
- 确保用户具有适当的 MySQL 权限
路径解析 如果遇到错误“Could not connect to MCP server 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';
```

贡献

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

开发设置

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

项目路线图

我们正在积极努力增强此 MCP 服务器。请查看我们的 CHANGELOG.md 以获取有关计划功能的详细信息，包括：

具有预处理语句的增强查询功能
高级安全功能
性能优化
全面监控
扩展的模式信息

如果您想为这些领域的任何一个做出贡献，请查看 GitHub 上的问题或打开一个新问题来讨论您的想法。

提交更改

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

许可证

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