mysql-mcp

MySQL MCP Server (mysql-mcp)

📚 完整文档（Wiki） • 更新日志 • 安全 • 发布文章

💎 价值主张

将 AI Agent 集成到生产就绪的 MySQL 环境中。通过 HTTP 传输部署 MCP v2 无状态架构。通过 Code Mode 优化令牌效率。使用 OAuth 2.1 保护数据库。

🎯 发挥核心优势

功能	描述
专业工具	使用适用于核心 CRUD、JSON、空间数据、文档存储和集群的专业工具。
资源	实时监控架构、性能指标、进程列表、复制状态和 InnoDB 诊断信息。
AI 驱动的提示词	执行用于构建查询、设计架构、调优性能和设置基础设施的引导式工作流。
代码模式	在安全的沙箱 V8 隔离环境中整合操作，减少大模型 Token 消耗。
Token 优化的载荷	最大限度地提高 Token 效率。使用可选标志缩减大型载荷的响应大小。
OAuth 2.1 安全性	通过符合 RFC 标准的严格作用域和 Keycloak 集成，实施细粒度访问控制。
智能工具筛选	使用工具组和快捷方式，满足 IDE 的工具数量限制。
可流式传输和无状态 HTTP	支持 MCP v2 可流式传输 HTTP 和无状态 HTTP 部署。
连接池	利用内置连接池，高效处理高并发数据库访问。
生态系统集成	直接通过 Agent 管理 MySQL Router、ProxySQL 和 MySQL Shell 实用工具。
高级加密	强制使用 TLS/SSL 连接。轻松管理数据脱敏、加密监控和合规性。
面向生产环境的安全性	通过参数化查询防止 SQL 注入。依靠严格的输入验证和审计日志记录。
确定性错误	接收包含可执行建议的结构化响应。杜绝静默失败和原始异常。
可观测性	导出 Prometheus 指标。使用 Dozzle 跟踪容器日志，并通过 Grafana Alloy/Loki 跟踪审计记录。
严格的 TypeScript	依托完善的测试套件，使用严格的 TypeScript。
符合 MCP v2 规范	全面支持 MCP v2 规范，包括无状态路由、缓存、安全提示和通知。

---

🤖 使用引导式工作流自动执行任务

此服务包含用于引导式工作流的智能提示词：

提示词	描述
mysql_tool_index	包含分类的完整工具索引
mysql_quick_query	快速执行查询的快捷方式
mysql_quick_schema	快速探索架构
mysql_setup_observability	完整的可观测性技术栈设置指南（Datadog 等）

注意：这只是可用提示词的一个子集。使用 mysql_tool_index 发现完整的引导式工作流列表。

---

📊 使用资源增强可观测性

此服务提供一套全面的资源，用于数据库可观测性和遥测：

资源	类别	描述
mysql://schema	核心	完整的数据库架构
mysql://tables	核心	包含元数据的表列表
mysql://variables	核心	服务配置变量
mysql://status	核心	服务状态指标
mysql://processlist	核心	活动连接和查询
mysql://pool	核心	连接池统计信息
mysql://capabilities	扩展	服务版本、功能和工具类别
mysql://health	扩展	全面的数据库健康状态
mysql://performance	扩展	查询性能指标
mysql://indexes	扩展	索引使用情况和统计信息
mysql://replication	扩展	复制状态和延迟
mysql://innodb	扩展	InnoDB 缓冲池和引擎指标
mysql://events	领域	事件调度器状态和已计划事件
mysql://sysschema	领域	sys 架构诊断摘要
mysql://locks	领域	InnoDB 锁竞争检测
mysql://cluster	领域	Group Replication / InnoDB Cluster 状态
mysql://spatial	领域	空间列和索引
mysql://docstore	领域	文档存储集合
mysql://insights	分析	来自 mysql_append_insight 的业务洞察备忘录
mysql://metrics	可观测性	内存中的令牌用量、延迟和请求指标
mysql://audit	可观测性	系统错误的取证记录和快照
mysql://help	文档	关键注意事项和高级 API 参考
mysql://help/{group}	文档	按组动态生成的工具参考（例如，core、codemode）

---

🚀 部署你的 AI 数据库

满足先决条件

• Node.js >= 24.0.0（有关固定的本地开发版本，请参阅 .node-version）
• Bun（用于执行仓库自动化脚本）
• MySQL 服务
• pnpm

安装服务

通过 NPM / PNPM 安装

pnpm add -g @neverinfamous/mysql-mcp

运行服务：

mysql-mcp --transport stdio --mysql "mysql://mcp_user:secure_password@localhost:3306/testdb"

或者使用 npx，无需安装：

npx @neverinfamous/mysql-mcp --transport stdio --mysql "mysql://mcp_user:secure_password@localhost:3306/testdb"

使用 Docker 运行

命名空间说明： Docker 镜像使用 writenotenow 命名空间。GitHub 仓库使用 neverinfamous。

Linux 用户： 在 Linux 上使用 host.docker.internal 时，请使用 --add-host host.docker.internal:host-gateway 运行容器。

docker run -i --rm -v ./data:/app/data -v ./logs:/var/log/mysql-mcp writenotenow/mysql-mcp:latest \
  --transport stdio \
  --allowed-io-roots /app/data \
  --mysql "mysql://mcp_user:[email protected]:3306/testdb"

通过 Docker Compose 启用可观测性

使用随附的模板启动完整的可观测性技术栈，其中包括 Datadog、OpenTelemetry、Prometheus 和 Grafana。此操作会启动 MCP 服务、MySQL 数据库、Redis 和可观测性边车：

cd examples/basic-mysql-datadog
cp .env.example .env
docker compose up -d

• Grafana： 可通过 http://localhost:3001 访问（已预加载仪表板）。
• Prometheus： 可通过 http://localhost:9090 访问。
• MCP 服务： 可通过 http://localhost:3000 访问。

遵循 Datadog 和 OpenTelemetry 可观测性规则

Datadog 约束：

• 身份验证：使用 pup CLI 进行身份验证。
• 自动发现：避免重复的自动发现配置。为容器添加标准跟踪标签（tags.datadoghq.com/env、tags.datadoghq.com/service、tags.datadoghq.com/version）。
• WSL2 加固限制：强制设置 stop_grace_period: 30s、mem_limit: 1536m，并将 OpenMetrics 超时设为 10s。
• 主机配置：使用 DD_HOSTNAME 和原生 /etc/docker/daemon.json cgroup 配置（"default-cgroupns-mode": "host"）。禁用 DD_EXTRA_PERFORMANCE_METRICS。
• Windows 文件跟踪：请注意，使用 Docker/WSL2 映射日志时，可能会遇到 Windows inotify 跟踪问题。

OpenTelemetry 规则：

• 语义约定：强制采用 gen_ai.* 语义。
• 插桩：尽可能使用自动插桩。
• 上下文传播：确保传播 traceparent 和 tracestate。
• 处理和日志记录：使用批处理器，并确保日志采用 JSON 格式。

审计架构和导出器健康检查：

• 主 MCP 服务通过 --audit-log 标志将执行跟踪写入 mcp-audit.jsonl。
• 指标导出器作为独立的 sidecar 进程运行。它使用 AUDIT_LOG_PATH 环境变量读取 mcp-audit.jsonl 并计算指标。
• 导出器通过将自身的 --audit-log 标志设为 exporter-audit.jsonl，隔离其内部日志。
• 指标服务器和导出器共享一个进程。两者都在端口 3000 上运行，以避免端口冲突。
• 导出器健康检查：wget --spider -q http://127.0.0.1:3000/metrics

从源代码构建

git clone https://github.com/neverinfamous/mysql-mcp.git
cd mysql-mcp
pnpm install
pnpm run build
node dist/cli.js --transport stdio --mysql "mysql://mcp_user:secure_password@localhost:3306/testdb"

---

🏗️ 使用基础设施模板

我们在 examples/ 目录中提供可用于生产环境的 Docker Compose 模板。使用这些模板可快速启动测试环境。模板开箱即包含完整的 Datadog 可观测性功能（指标、APM 和日志）。

• 基础模板： 轻量级的单节点 MySQL 配置，适合快速上手。
• 企业级 HA 模板： 高可用 InnoDB Cluster，搭配 MySQL Router 和 ProxySQL，适合搭建预发布环境或生产副本。
• 完整可观测性生态系统： 完整的企业级监控技术栈，包含 Datadog、Prometheus、Grafana、Loki 和 Alloy。有关指标配置的详细说明，请参阅 可观测性 Wiki。

请参阅各目录中的 README，了解快速入门说明。

---

⚡ 使用 Code Mode 优化令牌用量

Code Mode（mysql_execute_code）通过在安全沙箱中整合操作来减少令牌用量。

代码在 C++ V8 isolate 沙箱中安全执行。它强制执行严格的堆内存限制，并支持同步终止。原生封装器会跨边界映射所有 API 调用。这确保了纵深防御和整个集群通用的限制：

强制执行引擎级限制

• ✅ 严格的 V8 Isolate 边界 — 代码在物理隔离的 V8 isolate 中执行，确保原生对象和原型无法跨越边界。
• ✅ 内存和 CPU 约束 — 在 C++ 层强制执行，包括同步超时和严格的堆内存限制。
• ✅ 通过引用绑定 API — 使用 ivm.Reference 封装器安全地注入 MySQL 方法。

静态验证代码

• ✅ 全面屏蔽危险模式 — 正则表达式规则会屏蔽 require()、import()、eval()、Function、process 和 __proto__。也会屏蔽文件系统和网络访问以及系统命令。
• ✅ Unicode 和注释清理 — 移除注释并执行 NFKC 规范化，以防止绕过正则表达式检查。
• ✅ 可配置的代码输入限制 — 防止基于载荷的资源耗尽。

保护运行时

• ✅ RPC 配额 — 限制每次执行的 RPC API 调用次数，防止无限循环。
• ✅ 执行超时 — 强制执行超时，防止资源耗尽。可通过架构 timeout 配置。
• ✅ 出口边界强制执行 — 流式 JSON.stringify 序列化在超出大小上限时会中途中止。
• ✅ 速率限制 — 强制执行每个客户端的限制（CODEMODE_RATE_LIMIT_MAX）。使用 Redis，并在其不可用时回退到内存。
• ✅ 只读强制执行 — 当 readonly: true 时，不执行写入方法，而是返回结构化错误。
• ✅ 审计日志 — 记录每次执行的 UUID、客户端 ID、指标和已脱敏的代码预览。
• ✅ 管理员权限范围 — 启用 OAuth 时，Code Mode 需要 admin 权限范围。
• ✅ 完整 API 访问权限 — 通过 mysql.* 命名空间公开所有工具组。

⚡ 仅运行 Code Mode

仅启用 Code Mode 运行。单个工具即可提供完整的能力访问权限。建议的 IDE 配置请参阅下方的 选项 1：Code Mode。

这仅公开 mysql_execute_code。Agent 使用类型化 SDK 编写 JavaScript。它们可以组合查询，并跨工具组串联操作。在一次执行中返回所需的确切数据。这符合标准的无服务器边缘执行模式，并确保令牌成本固定。

提示

最大限度节省令牌： 指示 AI Agent 优先使用 Code Mode。

"使用 mysql-mcp 时，多步骤操作优先使用 mysql_execute_code（Code Mode）。这样可以最大限度减少令牌用量。"

如需最大限度节省令牌，请使用 --tool-filter codemode，仅将 Code Mode 作为工具运行。完整的 API 文档请参阅 Code Mode wiki。

---

🌐 通过 Streamable 和 Stateless HTTP 启用远程访问

何时使用 HTTP 模式： 将 mysql-mcp 部署为独立服务。多个客户端可以远程连接。本地开发请使用 stdio 模式。

HTTP 模式的使用场景：

• 在可通过网络访问的 Docker 容器中运行服务
• 部署到云平台（AWS、GCP、Azure）
• 启用 OAuth 2.1 身份验证，满足企业安全要求
• 让多个 AI 客户端共用一个数据库连接

使用 HTTP 传输实现远程访问：

npx -y @neverinfamous/mysql-mcp \
  --transport http \
  --server-host 0.0.0.0 \
  --port 3000 \
  --allowed-io-roots /path/to/data \
  --mysql "mysql://mcp_user:secure_password@localhost:3306/testdb"

Docker：

docker run --rm -p 3000:3000 \
  -v ./data:/app/data \
  -v ./logs:/var/log/mysql-mcp \
  -e MCP_AUTH_TOKEN=my-secret-token \
  writenotenow/mysql-mcp:latest \
  --transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots /app/data --mysql "mysql://mcp_user:[email protected]:3306/testdb"

服务支持 Streamable HTTP 和 Stateless HTTP 部署。有状态和无状态客户端均可连接：

使用 Streamable HTTP（推荐）

现代 MCP 协议——单一端点、基于会话：

方法	端点	用途
POST	/mcp	JSON-RPC 请求（initialize、tools/list 等）
GET	/mcp	用于服务通知的 SSE 流
DELETE	/mcp	终止会话

速率限制： HTTP 传输按 IP 限制速率（默认每分钟 100 次，可通过 MCP_RATE_LIMIT_MAX 配置）。可使用 Redis 在不同部署间分配限额，并在 Redis 不可用时优雅地回退到内存。

服务通过 Mcp-Session-Id 标头管理会话。

以无状态模式运行

在不需要会话时，使用无状态部署：

node dist/cli.js --transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots /path/to/data --stateless --mysql "mysql://mcp_user:secure_password@..."

在无状态模式下：GET /mcp 返回 405。DELETE /mcp 返回 204。每个 POST /mcp 请求都会实例化一个无状态 HTTP 传输。

访问实用工具端点

方法	端点	用途
GET	/health	健康检查（不受速率限制，始终可用于监控）
GET	/metrics	导出 Prometheus 指标（启用 --metrics-export 后可用）

🔐 使用身份验证保护数据

mysql-mcp 支持 HTTP 传输的两种身份验证机制：

使用 Bearer 令牌进行身份验证（--auth-token）

在开发环境中使用轻量级身份验证：

node dist/cli.js --transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots /path/to/data --auth-token my-secret --mysql "mysql://mcp_user:secure_password@..."

# Or via environment variable
export MCP_AUTH_TOKEN=my-secret
node dist/cli.js --transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots /path/to/data --mysql "mysql://mcp_user:secure_password@..."

客户端必须在所有请求中包含 Authorization: Bearer my-secret。/health 和 / 除外。未经身份验证的请求会收到 401。根据 RFC 6750，响应会包含 WWW-Authenticate: Bearer 标头。

使用 OAuth 2.1 进行身份验证

在生产部署中使用完整的 OAuth 2.1：

node dist/cli.js \
  --transport http \
  --server-host 0.0.0.0 \
  --port 3000 \
  --allowed-io-roots /path/to/data \
  --mysql "mysql://mcp_user:secure_password@localhost:3306/testdb" \
  --oauth-enabled \
  --oauth-issuer https://localhost:8080/realms/mysql-mcp \
  --oauth-audience mysql-mcp-client

其他标志： --oauth-jwks-uri <url>（省略时会自动发现）、--oauth-clock-tolerance <seconds>（默认值：60）。

强制执行 OAuth 作用域

使用 OAuth 作用域强制实施访问控制：

作用域	访问级别
read	只读查询（SELECT、EXPLAIN）
write	读写操作
admin	完整管理权限
full	授予所有访问权限
db:{name}	访问特定数据库
table:{db}:{table}	访问特定表

确保符合 RFC 规范

此实现遵循完整的 OAuth 2.1，适用于生产环境中的多租户部署：

• ✅ RFC 9728 受保护资源元数据（/.well-known/oauth-protected-resource）
• ✅ RFC 8414 授权服务器发现，支持缓存
• ✅ RFC 7591 OAuth 2.1 动态客户端注册
• ✅ 支持 JWKS 的 JWT 验证（TTL：1 小时）
• ✅ MySQL 专用作用域：read、write、admin、full、db:{name}、table:{db}:{table}
• ✅ 通过 AsyncLocalStorage 上下文传递实现逐工具作用域强制执行

Keycloak 用户须知： 为客户端添加 Audience mapper。这会包含正确的 aud 声明。（Client → Client scopes → dedicated scope → Add mapper → Audience）

说明

逐工具作用域强制执行： 服务会在工具级别强制执行作用域。每个工具组都需要特定的作用域。启用 OAuth 后，每次调用工具时，都会在执行前检查调用方令牌的作用域。未配置 OAuth 时，服务会完全跳过作用域检查。

警告

未启用身份验证的 HTTP： 在未启用身份验证的情况下公开 --transport http 会授予不受限制的访问权限。生产环境中的 HTTP 部署务必启用身份验证。详情请参阅 SECURITY.md。

⚡ 使用客户端配置简化 AI 集成

安装 Agent Skills

为实现最佳 AI 性能，mysql-mcp 在 skills/ 目录中提供了专用的 Agent 指令。这些技能会指导 AI 编码助手（如 Cline、Antigravity 或 Copilot）如何有效使用服务功能、工具筛选器和 Code Mode。

安装方法：将 skills/ 目录中的 .md 文件复制到 AI 助手指定的技能或自定义指令文件夹（例如 .cursor/rules/、.agents/skills/ 等）。这样 Agent 就能自主探索 mysql-mcp 生态系统，而不会臆造使用方式。

配置 IDE 设置

在 IDE 的 MCP 设置文件中添加配置：

选项 1：Code Mode（最大限度节省令牌，🌟 推荐）

适用场景： 通用 MySQL AI Agent 任务。提供 mysql_execute_code，以访问完整的沙箱化工具集。

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@neverinfamous/mysql-mcp",
        "--transport",
        "stdio",
        "--tool-filter",
        "codemode"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "mcp_user",
        "MYSQL_PASSWORD": "secure_password",
        "MYSQL_DATABASE": "testdb"
      },
      "timeout": 600
    }
  }
}

选项 2：Cluster（用于 InnoDB Cluster 监控的工具）

适用场景： 监控 InnoDB Cluster、Group Replication 状态和集群拓扑。

⚠️ 前提条件：

• 必须配置并运行 InnoDB Cluster，且启用 Group Replication
• 直接连接到集群节点（例如 localhost:3307），不要连接独立的 MySQL 实例
• 使用具有相应权限的 cluster_admin 或 root 用户
• 集群设置说明请参阅 MySQL Ecosystem Setup Guide

{
  "mcpServers": {
    "mysql-mcp-cluster": {
      "command": "npx",
      "args": [
        "-y",
        "@neverinfamous/mysql-mcp",
        "--transport",
        "stdio",
        "--tool-filter",
        "cluster"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3307",
        "MYSQL_USER": "cluster_admin",
        "MYSQL_PASSWORD": "cluster_password",
        "MYSQL_DATABASE": "mysql"
      },
      "timeout": 600
    }
  }
}

选项 3：生态系统（适用于 InnoDB Cluster 部署的工具）

适用场景： MySQL Router、ProxySQL、MySQL Shell 和 InnoDB Cluster 部署。

⚠️ 前置条件：

• InnoDB Cluster 需要已运行的集群。这将启用 Router REST API 身份验证。
• Router REST API 使用自签名 HTTPS 证书。设置 MYSQL_ROUTER_INSECURE=true 可跳过验证。
• X Protocol： InnoDB Cluster 默认包含 MySQL X Plugin。将 MYSQL_XPORT 设置为 Router 的 X Protocol 端口（例如 6448）。这将启用 mysqlsh_import_json 和 docstore 工具
• 详细说明请参见 MySQL Ecosystem Setup Guide

{
  "mcpServers": {
    "mysql-mcp-ecosystem": {
      "command": "npx",
      "args": [
        "-y",
        "@neverinfamous/mysql-mcp",
        "--transport",
        "stdio",
        "--tool-filter",
        "ecosystem"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3307",
        "MYSQL_XPORT": "6448",
        "MYSQL_USER": "cluster_admin",
        "MYSQL_PASSWORD": "cluster_password",
        "MYSQL_DATABASE": "testdb",
        "MYSQL_ROUTER_URL": "https://localhost:8443",
        "MYSQL_ROUTER_USER": "rest_api",
        "MYSQL_ROUTER_PASSWORD": "router_password",
        "MYSQL_ROUTER_INSECURE": "true",
        "PROXYSQL_HOST": "localhost",
        "PROXYSQL_PORT": "6032",
        "PROXYSQL_USER": "radmin",
        "PROXYSQL_PASSWORD": "radmin",
        "MYSQLSH_PATH": "mysqlsh"
      },
      "timeout": 600
    }
  }
}

注意： 端口 6448 是标准的 MySQL Router X Protocol 端口。

自定义说明：

• 将 /path/to/mysql-mcp/ 替换为实际安装路径。仅在从源代码构建时需要此操作。直接运行本地文件时也需要此路径。
• 使用实际值更新凭据
• 对于 Windows：使用正斜杠（例如 C:/mysql-mcp/dist/cli.js），或对反斜杠进行转义
• 对于 Windows MySQL Shell："MYSQLSH_PATH": "C:\\Program Files\\MySQL\\MySQL Shell\\bin\\mysqlsh.exe"
• Router 身份验证： Router REST API 会根据 InnoDB Cluster 元数据进行身份验证。集群必须处于运行状态，身份验证才能正常工作。
• 集群资源： 连接到 InnoDB Cluster 节点，即可使用 mysql://cluster 资源

📖 更多配置选项请参见 Configuration Wiki。

---

🔗 集成任何 MySQL 环境

场景	要使用的主机	连接字符串示例
主机上的 MySQL	localhost / host.docker.internal	mysql://mcp_user:secure_password@localhost:3306/testdb
Docker 中的 MySQL	容器名称或网络	mysql://mcp_user:secure_password@mysql-container:3306/testdb
远程/云端 MySQL	主机名或 IP	mysql://mcp_user:[email protected]:3306/testdb

连接到主机上的 MySQL

对于本机安装，请使用 localhost。如果在 Docker 中运行服务，请使用 host.docker.internal：

[
  "--mysql",
  "mysql://mcp_user:[email protected]:3306/testdb"
]

连接到另一个 Docker 容器中的 MySQL

对于 Docker 配置，请使用 host.docker.internal。对于 Docker Compose，请使用 mysql 服务名称。

创建网络并运行 MySQL：

docker network create mynet
docker run -d --name mysql-db --network mynet -e MYSQL_ROOT_PASSWORD=pass mysql:latest

在同一网络上运行 MCP 服务：

docker run -i --rm --network mynet writenotenow/mysql-mcp:latest \
  --transport stdio --mysql "mysql://mcp_user:secure_password@mysql-db:3306/testdb"

连接到远程/云端 MySQL（RDS、Cloud SQL 等）

直接使用远程主机名：

[
  "--mysql",
  "mysql://mcp_user:[email protected]:3306/testdb"
]

提供商	主机名示例
AWS RDS	your-instance.xxxx.us-east-1.rds.amazonaws.com
Google Cloud SQL	project:region:instance（通过 Cloud SQL Proxy）
Azure MySQL	your-server.mysql.database.azure.com
PlanetScale	aws.connect.psdb.cloud（需要 SSL）
DigitalOcean	your-cluster-do-user-xxx.db.ondigitalocean.com

提示： 确保远程 MySQL 服务允许来自 Docker IP 范围的连接。请确认防火墙/安全组允许端口 3306 通信。

---

🛠️ 使用工具筛选优化限制

重要

Cursor 等 AI IDE 有工具数量限制。请筛选工具，以确保符合 IDE 的限制。我们提供了许多专用工具。 所有快捷方式和工具组默认都包含 Code Mode。如需排除它，请在筛选器中添加 -codemode：--tool-filter core,json,-codemode

发现筛选选项

--tool-filter 参数接受快捷方式、分组或工具名称——可自由组合：

筛选模式	示例	说明
仅快捷方式	starter	使用预定义组合
仅分组	core,json,transactions	组合各个分组
快捷方式 + 分组	starter,spatial	扩展快捷方式
快捷方式 - 工具	starter,-mysql_drop_table	移除指定工具

使用预定义快捷方式

快捷方式	用途	包含内容
starter	标准包	core, json, transactions, text, codemode
essential	最小占用	core, transactions, codemode
dev-power	高级开发者	core, schema, performance, fulltext, transactions, codemode
dev-analytics	开发者分析	core, stats, performance, codemode
ai-data-nosql	AI NoSQL 数据	core, json, docstore, codemode
ai-search	AI 搜索	core, text, fulltext, vector, codemode
ai-spatial	AI 空间分析师	core, spatial, transactions, codemode
ai-vector	AI 向量分析师	core, vector, fulltext, codemode
dba-monitor	DBA 监控	core, monitoring, performance, sysschema, optimization, codemode
dba-manage	DBA 管理	core, admin, backup, replication, partitioning, events, codemode
dba-secure	DBA 安全	core, security, roles, transactions, codemode
dba-schema	DBA 架构	core, schema, introspection, migration, codemode
base-relational	关系型基础	core, transactions, text, schema, codemode
base-analytics	分析基础	stats, events, codemode
base-nosql	NoSQL 基础	docstore, spatial, vector, codemode
ecosystem	外部工具	cluster, proxysql, router, shell, codemode

按工具分组筛选

注意：所有分组都会自动添加 Code Mode（mysql_execute_code）。

分组	说明
codemode	Code Mode（沙盒化代码执行）🌟 推荐
core	读写查询、表、索引
transactions	BEGIN、COMMIT、ROLLBACK、保存点
json	JSON 函数、合并、差异、统计
text	REGEXP、LIKE、SOUNDEX
fulltext	自然语言和布尔搜索
performance	EXPLAIN、查询分析、异常检测
optimization	索引提示、全库审计、EXPLAIN 建议
admin	OPTIMIZE、ANALYZE、CHECK、洞察
monitoring	PROCESSLIST、状态变量
backup	导出、导入、mysqldump、审计备份
replication	主/从、binlog
partitioning	分区管理
schema	视图、存储过程、触发器、约束
introspection	依赖关系图、级联模拟、快照
migration	架构版本控制、应用、回滚、历史记录
shell	MySQL Shell 实用工具
events	事件调度器管理
sysschema	sys 架构诊断
stats	统计分析、窗口函数、采样
spatial	空间/GIS 操作
security	审计、SSL、加密、脱敏
roles	MySQL 角色管理
docstore	Document Store 集合
cluster	Group Replication、InnoDB Cluster
proxysql	ProxySQL 管理
router	MySQL Router REST API
vector	向量嵌入、KNN 搜索、混合搜索

---

审查语法参考

旧版语法（仍受支持）： 如果以负向筛选器开头（例如 -ecosystem），则会先启用所有工具，再减去指定的工具。

前缀	目标	示例	效果
(none)	快捷方式	starter	**白名单模式：**仅启用此快捷方式
(none)	分组	core	**白名单模式：**仅启用此分组
(none)	工具	mysql_read_query	**白名单模式：**仅启用此工具
+	分组	+spatial	将此分组中的工具添加到当前集合
-	分组	-admin	从当前集合中移除此分组中的工具
+	工具	+mysql_explain	添加一个特定工具
-	工具	-mysql_drop_table	移除一个特定工具

自定义工具选择

列出不带 + 前缀的工具名称，即可创建自定义白名单。

筛选最简单的方法是使用白名单模式。只需指定所需的快捷方式，其余内容都会自动禁用。

# Enable specific tools (whitelist mode)
--tool-filter "mysql_read_query,mysql_write_query,mysql_list_tables"

# Mix tools from different groups
--tool-filter "mysql_read_query,mysql_explain,mysql_json_extract"

# Combine with a shortcut or group
--tool-filter "starter,+mysql_spatial_distance,+mysql_json_diff"

自动化客户端需要最小能力集时，请使用此功能。

📖 请参阅 工具筛选 Wiki，了解高级示例。

---

🔧 使用高级配置进行自定义

有关设置详情，请参阅项目根目录中的配置模板。

如需专门的设置，请参阅以下 Wiki 页面：

主题	描述
MySQL Router	配置 Router REST API 访问，以用于 InnoDB Cluster
ProxySQL	配置 ProxySQL 管理界面访问
MySQL Shell	配置 MySQL Shell 以执行转储/加载操作

---

⚡ 最大化服务性能

服务会缓存架构元数据，以减少工具/资源调用期间的重复查询。

查看性能基准

服务在核心执行路径上的处理能力达到每秒数百万次操作。这确保了极低的延迟和最高的吞吐量。每个组件都针对企业级工作负载进行了调优。享受亚毫秒级的沙盒冷启动和优化的反向查找。

基准测试基线：

• parseToolFilter：约 32,000-62,000 ops/sec
• CodeModeSandbox.create 冷启动：约 2.78M ops/sec
• 沙盒释放：约 2.37M ops/sec
• SandboxPool 初始化：约 109k ops/sec
• Set.has 工具检查：约 4.4M ops/sec
• Map.get 反向查找：约 4.5M ops/sec
• Map.get URI 匹配：约 5.1M ops/sec
• validateCode 安全短代码：约 173k ops/sec
• validateCode 已拦截：约 298k ops/sec
• checkRateLimit：约 205k ops/sec
• sanitizeResult 小型载荷：约 1.49M ops/sec
• 提示词架构解析：约 1.3M ops/sec

**提示：**开发时可降低 METADATA_CACHE_TTL_MS（例如 5000）。使用稳定架构进行生产时可提高该值（例如 300000 = 5 分钟）。

**载荷优化：**工具支持 summary: true 和 limit 参数，可精简大型载荷。

---

🎛️ 掌握服务配置

配置 CLI 选项

**注意：**CLI 标志列中标记为 — 的项目只能通过环境变量配置。 | 选项 | 环境变量 | 说明 | | ------------------------- | ----------------------- | --------------------------------------------------- | | --config, -c | — | 配置文件路径（.yaml 或 .json） | | --dump-config | — | 将当前配置转储到标准输出并退出 | | --version, -v | — | 显示版本号 | | --help, -h | — | 显示帮助 | | --json | — | 以 JSON 格式输出 | | --transport, -t | — | 传输类型：stdio、http、sse（默认：stdio） | | --port, -p | MYSQLMCP_PORT | http 传输的 HTTP 端口 | | --server-host | MCP_HOST | HTTP 传输绑定的主机（默认：localhost） | | --mysql, -m | — | MySQL 连接字符串 | | --mysql-host | MYSQL_HOST | MySQL 主机 | | --mysql-port | MYSQL_PORT | MySQL 端口 | | --mysql-user | MYSQL_USER | MySQL 用户名 | | --mysql-password | MYSQL_PASSWORD | MySQL 密码 | | --mysql-database | MYSQL_DATABASE | MySQL 数据库名称 | | --pool-size | MYSQL_POOL_SIZE | 连接池大小（默认：10） | | --pool-timeout | — | 获取连接的超时时间，单位为毫秒（默认：30000） | | --pool-queue-limit | — | 等待请求的队列上限（默认：0） | | --tool-filter, -f | TOOL_FILTER | 工具筛选字符串 | | --name | — | 服务名称 | | --auth-token | MCP_AUTH_TOKEN | 用于 HTTP 身份验证的简单 bearer token | | --stateless | — | 启用无状态 HTTP 模式 | | --trust-proxy | TRUST_PROXY | 信任客户端 IP 的 X-Forwarded-For | | --enable-hsts | MCP_ENABLE_HSTS | 启用 HTTP 严格传输安全（HSTS） | | --metrics-export | MCP_METRICS_EXPORT | 指标导出格式（例如：prometheus） | | --log-level | LOG_LEVEL | 日志级别：debug、info、warn、error | | --allowed-io-roots | ALLOWED_IO_ROOTS | 所有文件 I/O 操作允许路径的 JSON 数组或逗号分隔列表 | | --audit-log | MCP_AUDIT_LOG | 写入审计日志的文件路径（写入路径） | | — | AUDIT_LOG_PATH | 导出器读取审计日志的文件路径（读取路径） | | --audit-backup | — | 启用变更前快照 | | --audit-reads | — | 在审计日志中包含读取范围的工具调用 | | --audit-redact | — | 在审计日志中隐藏敏感参数 | | --audit-log-max-size | — | 轮换前的最大文件大小（字节） | | --audit-backup-data | — | 在变更前快照中包含示例数据 | | --audit-backup-max-size | — | 数据采集的最大表大小（字节） | | --oauth-enabled, -o | OAUTH_ENABLED | 启用 OAuth 2.1 身份验证 | | --oauth-issuer | OAUTH_ISSUER | 授权服务器 URL | | --oauth-audience | OAUTH_AUDIENCE | 预期的令牌受众 | | --oauth-jwks-uri | OAUTH_JWKS_URI | JWKS URI（自动发现） | | --oauth-clock-tolerance | OAUTH_CLOCK_TOLERANCE | 时钟容差，单位为秒 | | — | MYSQL_ROUTER_URL | MySQL Router URL | | — | MYSQL_ROUTER_USER | MySQL Router 用户 | | — | MYSQL_ROUTER_PASSWORD | MySQL Router 密码 | | — | MYSQL_ROUTER_INSECURE | 跳过 Router TLS 验证 | | — | MYSQL_ROUTER_API_VERSION | MySQL Router REST API 版本（默认：/api/20190715） | | — | PROXYSQL_HOST | ProxySQL 主机 | | — | PROXYSQL_PORT | ProxySQL 端口 | | — | PROXYSQL_USER | ProxySQL 用户 | | — | PROXYSQL_PASSWORD | ProxySQL 密码 | | — | MYSQLSH_PATH | MySQL Shell 可执行文件的路径 | | — | MYSQL_XPORT | MySQL X Protocol 端口（默认 33060） | | — | CODEMODE_ISOLATION | Code Mode 隔离级别（控制 V8 内存限制和严格程度） | | — | CODEMODE_MAX_RESULT_SIZE | Code Mode 结果负载的最大字节数 | | — | METADATA_CACHE_TTL_MS | 架构元数据的缓存 TTL | | — | REDIS_URL | Redis 连接 URL（用于速率限制） | | — | MCP_RATE_LIMIT_MAX | 每个 IP 每分钟的最大 HTTP 请求数（默认 100） | | — | CODEMODE_RATE_LIMIT_MAX| 每分钟的最大 Code Mode 执行次数（默认 60） | 优先级： 同时设置 --auth-token 和 --oauth-enabled 时，OAuth 2.1 优先。如果两者都未配置，服务端会发出警告并在无身份验证的情况下运行。

强制执行作用域

参见强制执行 OAuth 作用域。

📖 有关 Keycloak 设置和详细配置，请参阅 OAuth Wiki。

💻 通过贡献加速开发

有关设置，请参阅上文的 从源码构建。克隆后：

pnpm run lint
pnpm run typecheck
pnpm test
pnpm run test:e2e  # Run individually to avoid timeouts

使用 MCP Inspector 调试

使用 MCP Inspector 直观地测试和调试 mysql-mcp：

先构建服务端：

pnpm run build

启动 MCP Inspector 并连接 mysql-mcp：

npx @modelcontextprotocol/inspector node dist/cli.js \
  --transport stdio \
  --mysql mysql://mcp_user:secure_password@localhost:3306/testdb

打开 **http://localhost:5173**，以交互方式浏览所有工具、资源和提示词。

用于脚本编写的 CLI 模式：

列出所有工具：

npx @modelcontextprotocol/inspector --cli node dist/cli.js \
  --transport stdio --mysql mysql://... \
  --method tools/list

调用特定工具：

npx @modelcontextprotocol/inspector --cli node dist/cli.js \
  --transport stdio --mysql mysql://... \
  --method tools/call --tool-name mysql_list_tables

📖 有关详细用法，请参阅 MCP Inspector Wiki。

运行单元测试

项目使用 Vitest 保持较高的测试覆盖率。

pnpm test

生成覆盖率报告：

pnpm run test:coverage

测试基础设施：

• 在 src/__tests__/mocks/ 中集中管理模拟工厂
• 所有测试文件都使用共享模拟，以确保一致性
• 测试无需数据库连接即可运行（完全使用模拟）
• 单元测试使用模拟。E2E 和压力测试套件需要连接到实时数据库。

执行基准测试

项目包含一套性能基准测试，用于跟踪关键路径的效率，包括 Code Mode 沙盒初始化、工具筛选和 URI 路由。

pnpm run bench

---

贡献指南 • 安全策略 • MIT 许可证 • 行为准则