MCP Mysql Ops

MySQL操作和监控的MCP服务器




______________________________________________________________________

建筑与内部（DeepWiki）


______________________________________________________________________

概述

您正在与 MCP MySQL操作服务器，一个强大的工具，通过自然语言查询提供全面的MySQL数据库监控和分析功能。此服务器提供 19种专用工具 用于数据库管理、性能监控和系统分析。利用MySQL的性能模式和信息模式深入了解数据库操作和性能指标。

______________________________________________________________________

特性

• ✅ 零配置：适用于MySQL 5.7.9+和8.0+，具有自动版本检测功能。
• ✅ 自然语言：问“显示慢速查询”或“分析表大小”之类的问题
• ✅ 安全生产：只读操作，AWS RDS/Aurora MySQL兼容常规用户权限。
• ✅ 性能模式集成：使用MySQL内置的性能模式进行高级查询分析。
• ✅ 全面的数据库监控：存储引擎分析、连接监控和性能洞察。
• ✅ 智能查询分析：使用性能模式统计信息查询性能标识。
• ✅ 模式和结构发现：数据库结构探索，包括详细的表和索引分析。
• ✅ 存储引擎智能：InnoDB监控，表优化建议。
• ✅ 多数据库操作：无缝的跨数据库分析和监测。
• ✅ 企业就绪：与AWS RDS/Aurora MySQL兼容的安全只读操作。
• ✅ 开发者友好：简单的代码库，便于定制和工具扩展。

🔧 高性能

• 基于性能模式的查询监控和分析。
• 实时连接和过程监控。
• 存储引擎状态和优化分析。
• 数据库容量和表大小分析。
• 索引使用和效率跟踪。

工具使用示例

______________________________________________________________________

MCP-MySQL-Ops Usage Screenshot

______________________________________________________________________

MCP-MySQL-Ops Usage Screenshot

______________________________________________________________________

⭐ 快速入门（5分钟）

注： 这 mysql 集装箱包含在 docker-compose.yml 仅用于快速入门测试目的。您可以根据需要调整环境变量来连接到自己的MySQL实例。

如果你想使用自己的MySQL实例而不是内置的测试容器： - 在您的数据库中更新目标MySQL连接信息 .env 文件（请参阅MYSQL主机、MYSQL端口、MYSQL用户、MYSQL密码、MYSQL数据库）。 - 在 docker-compose.yml，注释掉（禁用） mysql 和 mysql-init-data 容器，以避免启动内置测试数据库。

快速入门/教程流程图

Flow Diagram of Quickstart/Tutorial

1.环境设置

备注：系统会自动处理用户权限——root用户和普通用户都受到适当的访问控制。

git clone https://github.com/call518/MCP-MySQL-Ops.git
cd MCP-MySQL-Ops

# Copy and check environment configuration
cp .env.example .env

默认配置（开箱即用）：

#### MySQL Root Configuration for Docker:
MYSQL_ROOT_HOST=%
MYSQL_ROOT_PASSWORD=changeme!@34

#### MySQL Host Configuration:
MYSQL_HOST=host.docker.internal
MYSQL_PORT=13306
MYSQL_USER=root
MYSQL_PASSWORD=${MYSQL_PASSWORD}
MYSQL_DATABASE=test_ecommerce

对于您自己的MySQL服务器：

# Edit .env file with your MySQL connection details
MYSQL_HOST=your-mysql-server.com
MYSQL_PORT=3306
MYSQL_USER=your_username     # Will auto-grant permissions on test DBs
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_default_db

# Then disable built-in containers in docker-compose.yml
# Comment out: mysql and mysql-init-data services

备注MySQL容器配置了适当的卷映射，用于数据持久性和初始数据库设置。

其他资源：

• MCP工具功能（Swagger）: http://localhost:8004/docs
• MCPO代理API文档: http://localhost:8004/mysql-操作/文档

2.运行Docker Stack

# Start all services (MySQL + MCP server + test interfaces)
docker-compose up -d

# Check container status
docker-compose ps

# Watch the logs (Ctrl+C to exit)
docker-compose logs -f mysql-init-data

⏱️ 容器启动顺序和等待时间：

• MySQL容器：首先启动并初始化数据库（~30-60秒）
• MySQL初始化数据：自动生成测试数据（约1-2分钟）
• MCP服务器MySQL准备就绪后启动（约10-20秒）
• OpenWeb用户界面：最后开始以确保所有服务可用（约10-30秒）

💡 请等待2-3分钟 让所有容器在访问web界面之前完全初始化。您可以通过以下方式监控启动进度：

# Monitor all container logs
docker-compose logs -f

# Check if all containers are healthy
docker-compose ps

3.自动生成测试数据

🎉 无需手动设置！ 测试数据在首次启动时由 mysql-init-data 集装箱。

自动发生的事情：

• ✅ 创建了4个综合测试数据库(test_ecommerce, test_analytics, test_inventory, test_hr)
• ✅ ~2745条具有适当外键关系的真实记录
• ✅ 自动为您配置用户权限 MYSQL_USER （来自.env）
• ✅ 测试为不同访问场景创建的用户和角色

手动执行（如果需要）：

# Force regenerate test data (optional)
docker-compose run --rm mysql-init-data /scripts/create-test-data.sh

# Check generation logs
docker logs mcp-mysql-ops-mysql-init-data

验证：

# Connect and verify test databases exist
docker exec -it mcp-mysql-ops-mysql-8 mysql -u [your_mysql_user] -p -e "SHOW DATABASES;"

4.访问OpenWebUI

🌐 Web界面： http://localhost:3004/

⏳ 重要：请稍候 2-3分钟 运行后 docker-compose up -d 以便所有容器完全初始化。OpenWebUI最后启动，以确保所有后端服务（MySQL、测试数据生成、MCP服务器）都已准备就绪。

快速状态检查：

# Verify all containers are running
docker-compose ps

# If any container shows "starting" or "unhealthy", wait a bit longer
# You can watch the startup logs:
docker-compose logs -f

5.在OpenWebUI中注册该工具

📌 备注：Web UI配置说明基于OpenWebUI v0.6.22。菜单位置和设置在较新版本中可能有所不同。

1. 使用管理员帐户登录OpenWebUI
2. 转到“设置”→ 顶部菜单中的“工具”。
3. 输入 mysql-ops 工具地址（例如。， http://localhost:8004/mysql-ops)连接MCP工具。
4. 设置Ollama或OpenAI。

6.完成！

祝贺 您的MCP MySQL操作服务器现在可以使用了。您可以开始使用自然语言查询来探索您的数据库。

🚀 尝试以下示例查询：

• “显示当前活动的连接”
• “当前服务器的状态和配置是什么？”
• “分析表大小和存储效率”
• “显示数据库大小信息”
• “哪些表的行数最多？”

______________________________________________________________________

安全和身份验证

承载令牌身份验证

对于 streamable-http 模式下，此MCP服务器支持承载令牌身份验证，以确保远程访问的安全。在生产环境中运行服务器时，这一点尤为重要。

配置

启用身份验证：

# In .env file
REMOTE_AUTH_ENABLE=true
REMOTE_SECRET_KEY=your-secure-secret-key-here

或者通过CLI：

python -m mcp_mysql_ops --type streamable-http --auth-enable --secret-key your-secure-secret-key-here

安全等级

1. stdio模式 （默认）：仅本地访问，无需身份验证
2. 可流式传输http+REMOTE_AUTH_ENABLE=false：无身份验证的远程访问⚠️ 不建议用于生产
3. 可流式传输http+REMOTE_AUTH_ENABLE=true：使用承载令牌身份验证进行远程访问✅ 建议用于生产

客户端配置

启用身份验证后，MCP客户端必须在授权标头中包含Bearer令牌：

{
  "mcpServers": {
    "mcp-mysql-ops": {
      "type": "streamable-http",
      "url": "http://your-server:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-secret-key-here"
      }
    }
  }
}

安全最佳实践

• 始终启用身份验证 在生产环境中使用流式http模式时
• 使用强随机生成的密钥 （建议使用32+个字符）
• 使用HTTPS 如果可能（使用SSL/TLS配置反向代理）
• 限制网络访问 使用防火墙或网络策略
• 定期旋转密钥 增强安全性
• 监控访问日志 未经授权的访问尝试

错误处理

当身份验证失败时，服务器返回：

• 401未经授权 用于丢失或无效的令牌
• 详细的错误消息 JSON格式用于调试

______________________________________________________________________

🐛 使用和配置

此MCP服务器支持两种连接模式： 标准 （传统）和 可流式传输http （基于Docker）。您可以使用CLI参数或环境变量配置传输模式。

配置优先级： CLI参数>环境变量>默认值

CLI参数

• --type (-t)：运输类型(stdio 或 streamable-http)-默认值： stdio
• --host：HTTP传输的主机地址-默认值： 127.0.0.1
• --port (-p)：HTTP传输的端口号-默认值： 8000
• --auth-enable：为可流式传输的http模式启用承载令牌身份验证-默认值： false
• --secret-key：承载令牌身份验证的密钥（启用身份验证时需要）

环境变量

环境设置

复制 .env.example 到 .env 并配置您的环境：

cp .env.example .env
# Edit .env file with your specific configuration

环境变量默认策略

身份验证变量：

• REMOTE_AUTH_ENABLE：如果未定义、注释掉或为空→ 默认为 false
• REMOTE_SECRET_KEY：如果未定义、注释掉或为空→ 默认为 "" （空字符串）

安全行为：

• 身份验证是 仅启用 当两个条件都满足时：

1. REMOTE_AUTH_ENABLE 显式设置为真值（true/1/yes/on） 1. REMOTE_SECRET_KEY 设置为非空字符串

• 如果任一条件失败，服务器将运行 无身份验证
• 这确保了安全的默认设置，并防止意外绕过身份验证

示例配置：

# Authentication disabled (all equivalent)
# REMOTE_AUTH_ENABLE=            # undefined/commented
REMOTE_AUTH_ENABLE=false         # explicit false
REMOTE_AUTH_ENABLE=""           # empty string

# Authentication enabled (requires both)
REMOTE_AUTH_ENABLE=true         # or 1, yes, on
REMOTE_SECRET_KEY=my-secret-key # non-empty string

______________________________________________________________________

🛠️ 本地开发与安装

对于希望在本地运行MCP服务器或将其集成到自己项目中的开发人员：

方法1：控制台脚本（推荐）

# Clone and install
git clone https://github.com/call518/MCP-MySQL-Ops.git
cd MCP-MySQL-Ops
pip install -e .

# Run with simple command
mcp-mysql-ops --type stdio
mcp-mysql-ops --type streamable-http --host 127.0.0.1 --port 8000

方法2：模块执行

# Clone and set PYTHONPATH
git clone https://github.com/call518/MCP-MySQL-Ops.git
cd MCP-MySQL-Ops
export PYTHONPATH=$(pwd)/src

# Run as module
python -m mcp_mysql_ops --type stdio
python -m mcp_mysql_ops --type streamable-http --host 127.0.0.1 --port 8000

💡 专业建议：使用方法1（控制台脚本）进行更清晰的集成。当您需要直接修改源代码时，方法2非常有用。

运行测试

有两个测试套件可供选择：

用一个命令运行所有内容

uv run pytest 自动启动Docker测试容器（MySQL 5.7、8.0、8.4），等待它们完全初始化（模式+种子数据+性能模式），运行所有测试，然后删除所有内容。

# Install dev dependencies (one-time)
uv sync --extra dev

# Run all tests (unit + integration) — Docker is managed automatically
uv run pytest -v

# Unit tests only (no Docker needed)
uv run pytest tests/test_version_compat.py -v

# Integration tests only
uv run pytest tests/test_tools_integration.py -v

# Run against a specific MySQL version only
uv run pytest -v -k MySQL80

备注：Docker必须正在运行。测试堆栈使用端口 3357 （MySQL 5.7）， 3380 （8.0），以及 3384 （8.4） 127.0.0.1. 如果容器已经在运行（例如在重复的调试运行之间），测试夹具会检测到它们并跳过向上/向下生命周期——这对快速迭代很有用。要手动预启动，请执行以下操作： ``bash docker compose -f tests/docker/docker-compose.test.yml up -d uv run pytest -v # reuses running containers, does not tear down ``

持续集成

每一次推动 main 每个pull请求都会触发 ，它在GitHub托管的运行器上运行单元套件和完整的MySQL 5.7/8.0/8.4集成矩阵。

______________________________________________________________________

（注）样品测试数据概述

测试数据生成系统遵循PostgreSQL MCP项目模式，使用专用的 mysql-init-data 容器，在首次启动时自动创建全面的测试数据库。

🚀 测试数据自动生成

这 mysql-init-data 容器（在docker compose.yml中定义）自动执行 scripts/create-test-data.sh 和 scripts/create-test-data.sql 在首次启动时，为MCP工具测试生成真实的业务数据。

总记录数： 所有测试数据库中约有2745条记录

已创建测试用户： app_readonly, app_readwrite, analytics_user, backup_user

用户权限管理： 系统自动创建指定 MYSQL_USER （来自.env），并仅授予4个测试数据库的完全权限，确保安全访问控制。

测试功能：

• ✅ 具有适当引用完整性的外键关系
• ✅ 各种存储引擎（InnoDB优化）
• ✅ 混合指数类型（用于/未用于测试指数分析工具）
• ✅ 用于分析测试的时间序列数据
• ✅ 跨多个领域的现实业务场景
• ✅ 具有隔离用户权限的安全测试环境

📋 PostgreSQL风格初始化模式

类似于 MCP PostgreSQL操作 项目，此MySQL实现使用：

• 专用初始化容器(mysql-init-data)用于一次性数据生成
• 健康检查依赖关系，确保MySQL在数据创建前准备就绪
• 创建数据库的根权限，然后将权限委托给指定用户
• 初始化过程中的全面日志记录和错误处理

______________________________________________________________________

工具兼容性矩阵

自动适应： 所有工具在支持的版本之间透明地工作，无需配置！

🟢 专业MySQL工具（19种可用工具）

🚀 性能模式增强工具（8个附加工具）

🚀 版本感知增强功能

📋 MySQL版本支持：需要 MySQL 5.7.9或更新版本 （支持5.7.9、8.0+、8.4+）。最小值由以下因素决定 performance_schema.processlist，在MySQL 5.7.9中引入，由 get_active_connections, get_connection_info，以及 get_lock_monitoringMySQL 8.1+和8.2+兼容性将在它们达到稳定发布状态时添加。

______________________________________________________________________

用法示例

Claude桌面集成

方法1：本地MCP（传输=“stdio”）

{
  "mcpServers": {
    "mcp-mysql-ops": {
      "command": "uvx",
      "args": ["--python", "3.11", "mcp-mysql-ops"],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "13306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "changeme!@34",
        "MYSQL_DATABASE": "test_ecommerce"
      }
    }
  }
}

方法2：远程MCP（传输=“可流式传输http”）

在MCP客户端主机上：

{
  "mcpServers": {
    "mcp-mysql-ops": {
      "type": "streamable-http",
      "url": "http://localhost:18004/mcp"
    }
  }
}

使用承载令牌身份验证（建议用于生产）：

{
  "mcpServers": {
    "mcp-mysql-ops": {
      "type": "streamable-http", 
      "url": "http://localhost:18004/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-secret-key-here"
      }
    }
  }
}

“显示MySQL服务器功能和版本信息。” Claude Desktop Integration

“把关系画成美人鱼图” Claude Desktop Integration

（可选）使用本地源运行：

{
  "mcpServers": {
    "mcp-mysql-ops": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.mcp_mysql_ops.mcp_main"],
      "env": {
        "PYTHONPATH": "/path/to/MCP-MySQL-Ops",
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "13306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "changeme!@34",
        "MYSQL_DATABASE": "test_ecommerce"
      }
    }
  }
}

以标准模式运行MCP服务器

/w Pypi和uvx（推荐）

# Stdio mode
uvx --python 3.11 mcp-mysql-ops \
  --type stdio

# HTTP mode
uvx --python 3.11 mcp-mysql-ops
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --log-level DEBUG

（选项）配置多个MySQL实例

{
  "mcpServers": {
    "MySQL-A": {
      "command": "uvx",
      "args": ["--python", "3.11", "mcp-mysql-ops"],
      "env": {
        "MYSQL_HOST": "a.foo.com",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "password",
        "MYSQL_DATABASE": "information_schema"
      }
    },
    "MySQL-B": {
      "command": "uvx",
      "args": ["--python", "3.11", "mcp-mysql-ops"],
      "env": {
        "MYSQL_HOST": "b.bar.com",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "password",
        "MYSQL_DATABASE": "information_schema"
      }
    }
  }
}

/w本地来源

# Method 1: Using installed console script (after pip install -e .)
mcp-mysql-ops --type stdio
mcp-mysql-ops --type streamable-http --host 127.0.0.1 --port 8000 --log-level DEBUG

# Method 2: Using module execution
PYTHONPATH=/path/to/MCP-MySQL-Ops/src
python -m mcp_mysql_ops --type stdio
python -m mcp_mysql_ops --type streamable-http --host 127.0.0.1 --port 8000 --log-level DEBUG

______________________________________________________________________

环境变量

备注: MYSQL_DATABASE 当没有指定特定数据库时，用作操作的默认目标数据库。在Docker环境中，如果设置为自定义数据库名称，则该数据库将在MySQL初始启动时自动创建。

用户权限管理：使用非根时 MYSQL_USER，初始化过程自动：

• 如果指定的用户不存在，则创建该用户
• 授予4个测试数据库的完全权限(test_ecommerce, test_analytics, test_inventory, test_hr)
• 通过仅限制对必要数据库的访问来维护安全性
• 通过自动信息模式/性能模式访问启用监控功能

______________________________________________________________________

先决条件

最低要求

• MySQL 5.7.9 或更新版本（支持5.7.9+、8.0+、8.4+；用MySQL 8.0.37测试）。不支持5.7.9之前的版本，因为服务器依赖于 performance_schema.processlist，在5.7.9中介绍。
• Python 3.11+
• MySQL服务器的网络访问
• 读取系统数据库的权限(information_schema, performance_schema)

推荐MySQL配置

⚠️ 性能监控设置: 一些MCP工具通过特定的MySQL配置参数提供了增强的功能。这些设置是 可选的 但建议进行全面监测：

通过这些设置增强的工具:

• get_server_status：启用性能模式后的更详细统计信息
• get_index_usage_stats：通过性能模式表统计信息增强
• get_connection_info：使用性能模式改进了连接跟踪

验证: 应用任何配置更改后，验证设置：

SHOW VARIABLES LIKE 'performance_schema';
SHOW VARIABLES LIKE 'information_schema_stats_expiry';

+----------------------------------+-------+
| Variable_name                    | Value |
+----------------------------------+-------+
| performance_schema               | ON    |
| information_schema_stats_expiry  | 86400 |
+----------------------------------+-------+

方法1:my.cnf配置（推荐用于自管理MySQL）

将以下内容添加到您的 my.cnf 或 my.ini:

[mysqld]
# Performance Schema (usually enabled by default in MySQL 8.0+)
performance_schema = ON

# Enhanced statistics collection
information_schema_stats_expiry = 0  # Real-time statistics (use 86400 for cached)

# Optional: Enhanced query logging (use carefully in production)
# slow_query_log = ON
# slow_query_log_file = /var/log/mysql/slow.log
# long_query_time = 2

然后重新启动MySQL服务器。

方法2:MySQL启动参数

对于Docker或命令行MySQL启动：

# Docker example
docker run -d \
  -e MYSQL_ROOT_PASSWORD=mypassword \
  mysql:8.0 \
  --performance-schema=ON \
  --information-schema-stats-expiry=0

# Direct mysqld command
mysqld \
  --performance-schema=ON \
  --information-schema-stats-expiry=0

方法3：动态配置（MySQL 8.0+、AWS RDS、Azure、GCP）

对于无法修改的托管MySQL服务 my.cnf，使用SQL命令更改动态设置：

-- Enable real-time statistics (requires SUPER privilege or SYSTEM_VARIABLES_ADMIN)
SET GLOBAL information_schema_stats_expiry = 0;

-- Verify Performance Schema status (usually enabled by default)
SHOW VARIABLES LIKE 'performance_schema';

-- Optional: Enable slow query log for enhanced monitoring
SET GLOBAL slow_query_log = 'ON';
SET GLOBAL long_query_time = 2;

会话级测试注意事项:

-- Set for current session only (temporary)
SET SESSION information_schema_stats_expiry = 0;

______________________________________________________________________

RDS/Aurora MySQL兼容性

• 此服务器是只读的，可在AWS RDS MySQL和Aurora MySQL上使用常规角色。所有核心功能都可以通过标准的信息模式和性能模式访问获得。
• RDS/Aurora MySQL 8.0+实例默认启用性能架构。
• 为了增强监控能力，请考虑参数组配置：

  -- Check Performance Schema status
  SHOW VARIABLES LIKE 'performance_schema';

  -- Verify Information Schema settings
  SHOW VARIABLES LIKE 'information_schema_stats_expiry';

  -- Recommended user permissions for monitoring
  GRANT SELECT ON *.* TO @'%';
  GRANT PROCESS ON *.* TO @'%';

______________________________________________________________________

查询示例

🟢 MySQL核心监控工具（始终可用）

• get_server_info

- “显示MySQL服务器版本和配置状态。” - “检查服务器系统变量和运行时配置。” - “显示MySQL服务器功能和版本信息。” - 📋 特性：服务器版本、系统变量、配置状态、功能可用性 - 🔧 MySQL 5.7.9+/8.0+：完全兼容，无需额外设置

• get_tabase_list

- “列出所有数据库及其大小。” - “显示包含字符集和排序规则信息的数据库列表。” - “显示数据库存储使用情况和表计数。” - 📋 特性：数据库大小、字符集、排序规则、表计数、存储使用情况 - 🔧 MySQL 5.7.9+/8.0+：使用信息模式获取全面的数据库信息

• get_table_list

- “列出test_ecommerce数据库中的所有表。” - “使用存储引擎和行数显示表信息。” - “显示表创建日期和更新时间戳。” - 📋 特性：表名、存储引擎、行数、大小、创建/更新时间 - ⚠️ 必需: database_name 必须指定参数 - 💡 用法：支持按表名模式进行筛选

• get_table_schema_info

- “显示test_ecommerce数据库中客户表的详细架构信息。” - “获取test_ecommerce数据库中产品表的列详细信息和约束。” - “使用test_ecommerce数据库中订单表的索引和外键分析表结构。” - “显示test_inventory数据库中所有表的架构概述。” - 📋 特性：列类型、约束、索引、外键、表元数据 - ⚠️ 必需: database_name 必须指定参数 - 💡 用法：离开 table_name 数据库范围的模式分析为空

• get_database_overview

- “显示test_ecommerce数据库的全面数据库概述。” - “获取test_analytics数据库结构和统计信息的详细摘要。” - “使用test_inventory数据库的表计数和大小分析数据库概述。” - “显示test_hr数据库的数据库结构摘要。” - 📋 特性：数据库概述、表统计、存储摘要、架构分析 - ⚠️ 必需: database_name 必须指定参数

• get_user_list

- “列出所有MySQL用户及其权限。” - “显示带有主机信息和帐户状态的用户帐户。” - “显示用户权限摘要和身份验证详细信息。” - 📋 特性：用户帐户、主机模式、权限、帐户状态、身份验证信息 - 🔧 MySQL 5.7.9+/8.0+MySQL 8.0中增强的用户管理信息+

• get_active_connections

- “显示所有活动连接及其详细信息。” - “列出包含用户和主机信息的当前数据库连接。” - “监视活动会话及其当前操作。” - “显示连接统计信息和进程信息。” - 📋 特性：活动连接、进程列表、连接详细信息、会话信息 - 🔧 MySQL 5.7.9+/8.0+：通过性能模式集成增强了流程信息

• get_server_status

- “显示MySQL服务器状态变量和性能计数器。” - “显示当前服务器性能指标和统计数据。” - “监控服务器运行状态和关键性能指标。” - “分析服务器运行状况指标和资源利用率。” - 📋 特性：状态变量、性能计数器、连接统计、资源度量 - 🔧 MySQL 5.7.9+/8.0+：全面的服务器状态监控

• get_table_size_info

- “显示test_ecommerce数据库的表和索引大小分析。” - “按数据和索引大小查找最大的表。” - “分析存储效率和表大小分布。” - “显示带有数据/索引比率的表大小详细信息。” - 📋 特性：表大小、索引大小、数据/索引比率、存储效率分析 - ⚠️ 必需: database_name 用于精确尺寸分析的参数

• get_database_size_info

- “显示数据库容量分析和存储使用情况。” - “按总大小查找最大的数据库。” - “显示全面的数据库大小统计信息。” - “分析跨数据库的存储分布。” - 📋 特性：数据库大小、表计数、存储分布、容量分析 - 🔧 MySQL 5.7.9+/8.0+：使用信息模式进行精确的尺寸计算

• get_index_usage_stats

- “分析索引使用情况和效率统计数据。” - “显示索引基数和选择性信息。” - “查找可能未使用或冗余的索引。” - “显示索引性能和使用模式。” - 📋 特性：索引统计、基数、选择性、使用分析、优化建议 - ⚠️ 必需: database_name 目标指标分析参数 - 💡 增强与：已启用性能模式以获取更详细的统计信息

🚀 版本增强工具

• get_server_info （增强！）

- “显示服务器版本和MySQL 8.0高级功能。” - “检查服务器兼容性和可用增强功能。” - “显示MySQL版本特定的功能和建议。” - 📈 MySQL 8.0+：增强的JSON支持、改进的性能模式、CTE支持、窗口函数 - 📊 MySQL 5.7.9+：具有基本JSON和性能模式支持的核心功能

💡 自然语言查询示例

带有真实提示的测试工具-切勿直接使用函数名：

• ✅ “显示当前服务器状态和关键性能指标”
• ❌ “运行get_server_status”

📊 监控示例：

• “存在哪些数据库，它们使用了多少空间？”
• “显示电子商务数据库中的所有表及其大小”
• “哪些表具有最多的行和最大的索引？”
• “显示当前数据库连接及其活动”
• “分析test_ecommerce数据库的模式结构”
• “显示MySQL服务器配置和性能状态”
• “列出所有用户及其数据库权限”
• “查找可能需要索引优化的表”

💡 专业建议：所有工具都支持使用 database_name 参数。这允许MySQL根用户从单个MCP服务器实例分析和监视多个数据库。

______________________________________________________________________

故障排除

连接问题

1. 检查MySQL服务器状态
2. 验证中的连接参数 .env 文件
3. 确保网络连接
4. 检查用户权限和身份验证

配置问题

1. “拒绝访问”错误：检查用户权限

   SHOW GRANTS FOR 'username'@'host';

监控用户设置的快速修复:

   -- Create monitoring user with necessary permissions
   CREATE USER 'monitoring'@'%' IDENTIFIED BY 'secure_password';
   GRANT SELECT ON *.* TO 'monitoring'@'%';
   GRANT PROCESS ON *.* TO 'monitoring'@'%';

1. 性能架构的“表不存在”：检查性能架构状态

   SHOW VARIABLES LIKE 'performance_schema';  -- Should be 'ON'

备注：MySQL 8.0+中默认启用性能模式，但在某些配置中可能会禁用。

1. 缺少数据库信息：验证信息架构访问权限

   SHOW VARIABLES LIKE 'information_schema_stats_expiry';
   SELECT COUNT(*) FROM information_schema.tables;

实时统计的快速修复:

   SET GLOBAL information_schema_stats_expiry = 0;

1. 应用配置更改:

- 自我管理：将设置添加到 my.cnf 并重新启动服务器 - 托管服务：使用 SET GLOBAL 用于动态变量或参数组 - 临时测试：使用 SET SESSION 仅适用于当前会话

性能问题

1. 使用 limit 减少结果大小的参数
2. 在非高峰时段运行监控
3. 运行分析之前检查数据库负载
4. 考虑设置 information_schema_stats_expiry 用于缓存统计信息

版本兼容性问题

有关更多详细信息，请参阅 ##工具兼容性矩阵

1. 先运行兼容性检查:

   # "Use get_server_info to check version and available features"

1. 了解功能可用性:

- MySQL 8.0+：所有功能均具有增强的性能模式 - MySQL 5.7.9+：具有基本性能模式支持的核心功能 - **早期版本（\ List[Dict[str, Any]]: """Your custom data retrieval function.""" # Example implementation - adapt to your service data_source = await get_data_connection(target_resource) results = await fetch_data_from_source( source=data_source, filters=your_conditions, aggregations=["count", "sum", "avg"], sorting=["count DESC", "timestamp ASC"] ) return results

#### 2. **创建您的MCP工具**

将您的工具功能添加到 `src/
/mcp_main.py`:

@mcp.tool() async def get_your_custom_analysis(limit: int = 50, target_name: Optional[str] = None) -> str: """ [Tool Purpose]: Brief description of what your tool does

[Exact Functionality]: - Feature 1: Data aggregation and analysis - Feature 2: Resource monitoring and insights - Feature 3: Performance metrics and reporting

[Required Use Cases]: - When user asks "your specific analysis request" - Your business-specific monitoring needs

Args: limit: Maximum results (1-100) target_name: Target resource/service name

Returns: Formatted analysis results """ try: limit = max(1, min(limit, 100)) # Always validate input

results = await get_your_custom_data(target_resource=target_name)

if results: results = results[:limit]

return format_table_data(results, f"Custom Analysis (Top {len(results)})")

except Exception as e: logger.error(f"Failed to get custom analysis: {e}") return f"Error: {str(e)}"

#### 3. **更新导入（如果需要）**

将辅助函数添加到导入中 `src/
/mcp_main.py`:

from .functions import ( # ...existing imports... get_your_custom_data, # Add your new function )

#### 4. **更新提示模板（推荐）**

将您的工具描述添加到 `src/
/prompt_template.md` 为了更好地识别自然语言：

Your Custom Analysis Tool

X. get_your_custom_analysis

Purpose: Brief description of what your tool does Usage: "Show me your custom analysis" or "Get custom analysis for database_name" Features: Data aggregation, resource monitoring, performance metrics Required: target_name parameter for specific resource analysis

#### 5. **测试你的工具**

Local testing

./scripts/run-mcp-inspector-local.sh

Or with Docker

docker-compose up -d docker-compose logs -f mcp-server

Test with natural language:

"Show me your custom analysis"

"Get custom analysis for target_name"

就是这样！您的自定义工具已准备好用于自然语言查询。

______________________________________________________________________

## 发展

### 测试与开发

Test with MCP Inspector

./scripts/run-mcp-inspector-local.sh

Direct execution methods for debugging

Method 1: Console script (after pip install -e .)

pip install -e . mcp-mysql-ops --log-level DEBUG

Method 2: Module execution

PYTHONPATH=src python -m mcp_mysql_ops --log-level DEBUG

Test with different MySQL versions

Modify MYSQL_HOST in .env to point to different MySQL instances

Run tests (if you add any)

uv run pytest

### 版本兼容性测试

MCP服务器自动适应MySQL 5.7.9+和8.0+版本。要跨版本测试，请执行以下操作：

1. **设置测试数据库**：不同的MySQL版本（5.7、8.0、8.1+）
1. **运行兼容性测试**：指向每个版本并验证工具行为
1. **检查特征检测**：确保正确的版本检测和功能可用性
1. **验证性能**：确认MySQL版本的最佳性能

______________________________________________________________________

## 安全须知

- 所有工具都是 **只读** -无数据修改功能
- 输出中隐藏了敏感信息（密码）
- 没有直接的SQL执行-只有预定义的安全查询
- 遵循最小特权原则
- 与MySQL安全最佳实践兼容

______________________________________________________________________

## 贡献

🤝 **有想法吗？发现虫子了吗？想添加酷炫的功能吗？**

我们总是很高兴欢迎新的贡献者！无论您是修复拼写错误、添加新的监控工具还是改进文档，每一份贡献都会使这个项目变得更好。

**贡献方式：**

- 🐛 报告问题或错误
- 💡 建议新的MySQL监控功能
- 📝 改进文档
- 🚀 提交拉取请求
- ⭐ 如果你觉得回购有用，请为其加星！

**专业提示：** 代码库的设计非常适合添加新工具。查看现有 `@mcp.tool()` 功能在 `mcp_main.py`.

______________________________________________________________________

## MCPO Swagger文件

> \[MCPO Swagger URL\]http://localhost:8004/mysql-操作/文档

![MCPO Swagger APIs](img/screenshot-swagger-api-docs.png)

______________________________________________________________________

## 许可证

自由使用、修改和分发 **MIT许可证**.

______________________________________________________________________

## ⭐ 其他项目

**同一作者的其他MCP服务器：**

- [MCP PostgreSQL操作](https://github.com/call518/MCP-PostgreSQL-Ops)
- [MCP-气流API](https://github.com/call518/MCP-Airflow-API)
- [MCP-Ambari-API公司](https://github.com/call518/MCP-Ambari-API)
- [LogSentinelAI-基于LLB的日志分析器](https://github.com/call518/LogSentinelAI)