AI导哈

MySQL只读查询服务器

基于NodeJS的MySQL只读查询服务器，为LLM提供数据库模式检查和只读查询功能。

  • by Churchechos
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 churchechos/mcp-server-mysql

使用说明

基于NodeJS的MySQL MCP服务器

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

安装

使用Smithery

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

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

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

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

使用MCP Get

您还可以使用安装此软件包 MCP获取:

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 （string）：要执行的SQL查询
    • 所有查询都在只读事务中执行
    • 支持用于安全参数处理的准备语句
    • 可配置的查询超时和结果分页
    • 内置查询执行统计

资源

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

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

安全功能

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

性能优化

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

监控与调试

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

配置

Smithery自动配置

如果您是使用Smithery安装的，那么您的配置已经设置好了。您可以通过以下方式查看或修改它：

smithery configure @benborla29/mcp-server-mysql

Claude桌面应用程序的手动配置

要为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": {
        // 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. 创建测试数据库和用户

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

运行测试

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

# 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. 路径解析 如果遇到错误“无法连接到MCP服务器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';

贡献

欢迎投稿！请随时向提交拉取请求 https://github.com/benborla/mcp-server-mysql

开发设置

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

项目路线图

我们正在积极致力于增强此MCP服务器。查看我们的 更改日志.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文件。

相关 MCP