MySQL Diag MCP

Read-only MCP server for MySQL performance diagnostics—processlist, locks, InnoDB, digests, replication lag—via SSH or direct TCP.

MySQL · MCP · Diagnostics · AI · Operations

GitHub →

Problem

During a MySQL slowdown you need processlist, lock waits, InnoDB status, and digests fast—without giving an agent a generic SQL socket into application data.

What it does

A read-only MCP server exposes a curated set of diagnostic-only tools for MySQL 5.7–8.4+: processlist, blocking chains, InnoDB status, statement digests, replication lag, and curated status/variable snapshots. The server detects the target version once per run and picks the right query variant where MySQL's schema changed between majors.

There is no generic SQL tool and this MCP never reads application row data—every tool is backed by a fixed query against information_schema / performance_schema / SHOW ... metadata. The one exception, mysql_explain, only runs EXPLAIN on a single SELECT/SHOW statement you provide; it never executes DML/DDL.

MySQL Diag MCP read-only diagnostics pathMCP clientagent · Cursormysql-diag-mcpstdio · fixed toolsSSH pathbastion · CLIDirectPyMySQLMySQL metadata onlyinfo_schema · perf_schema · SHOWprocesslistlocksInnoDBdigestsrepl lagEXPLAIN
MCP client calls fixed diagnostic tools over stdio. mysql-diag reaches MySQL via SSH or direct TCP—never ad-hoc DML.

Connection modes

Pick the path that fits via MYSQL_CONN_MODE:

  • ssh (default) — hop over SSH (optional bastion) and run the remote host's mysql CLI. Good when MySQL is only reachable from inside a network you access via SSH.
  • direct — connect with PyMySQL over TCP or a local unix socket. Use when you already have network/VPN access to the DB. Optional TLS via MYSQL_SSL_MODE.
MCP client → mysql-diag (stdio) → ssh [-J bastion] → mysql CLI
MCP client → mysql-diag (stdio) → PyMySQL → MySQL

Diagnostic tools

Fixed probes only—no free-form queries against app tables:

  • Processlist and session state
  • Lock waits and blocking chains
  • InnoDB status snapshots
  • Statement digests
  • Replication lag
  • Curated status / variable views
  • EXPLAIN for a single SELECT/SHOW

Ops notes

  • Prefer a dedicated mcp_diag MySQL user, not application root.
  • In SSH mode, passwords go through a remote --defaults-extra-file (not on ps argv).
  • Optional network transport (streamable-http / sse) for a shared service; auth tokens are required by default for non-stdio modes.

Full setup, env vars, and client registration live in the GitHub README.