A general purpose Model Context Protocol (MCP)
server for investigating MySQL 8 databases. It connects to a single
instance directly, over a unix socket, or through an SSH tunnel, and exposes a
curated set of read-only diagnostic tools: sessions, locks, transactions,
slow queries, InnoDB internals, schema, and replication.
It is designed for incident response and day-to-day troubleshooting, so it is
read-only by default and avoids impactful actions.
MCP server for read-only MySQL diagnostics
ดาว
1
เครื่องมือ
—
อัปไทม์
—
Features
Connect directly (TCP), via unix socket, or through an SSH tunnel (key,
password, or agent auth, with known_hosts verification).
Read-only by default. The generic query tool rejects anything that is not
SELECT/SHOW/EXPLAIN/DESCRIBE/WITH/USE, blocks stacked statements,
and the driver runs with multi-statements disabled.
System schemas only by default. Queries may only touch MySQL's own
catalogs (information_schema, performance_schema, mysql, sys), and live
statement text is masked, so the server never reads application row data unless
you opt in with --allow-user-data.
Per-query timeout and a configurable row cap on every result.
Session guardrails. Every connection is opened read-only (when --readonly)
with a max_execution_time and short lock-wait timeouts, so a diagnostic query
can never write, run away, or sit waiting on a lock.
Privilege-aware tools. At connect the server probes what the user can do
(PROCESS, REPLICATION CLIENT, performance_schema, sys) and hides the
tools that would just return "access denied".
Toolsets. Expose only the groups you need (--toolsets health,locks) or
cherry-pick individual tools (--tools mysql_query,mysql_ping).
Investigation runbooks. Ships MCP prompts (slow server triage, blocking
locks, replication lag, ...) that walk an agent through the right tools in order.
Targets MySQL 8.0.22 or newer and uses modern syntax (SHOW REPLICA STATUS, Replica_*/Source_* columns, and SHOW BINARY LOG STATUS on 8.4+).
MariaDB and MySQL 5.7 are rejected at connect.
25 diagnostic tools plus an optional, explicitly gated mysql_kill.
Install
Requires Go 1.25+.
go build -o mysql-mcp-server ./cmd/mysql-mcp-server
# or
make build
Docker
docker build -t mysql-mcp-server .
The server speaks MCP over stdio, so run it interactively and pass configuration
as environment variables. From an MCP client, use docker run -i --rm as the
command:
This server is read-only and limited to MySQL's system schemas by default, so it
does not read application data unless you opt in. See SECURITY.md
for the full safety model, operator guidance, and how to report a vulnerability.
Configuration
Every setting can be provided as an environment variable or a flag; flags take
precedence over environment variables, which take precedence over defaults.
Connection
Env
Flag
Default
Description
MYSQL_HOST
--host
127.0.0.1
MySQL host
MYSQL_PORT
--port
3306
MySQL port
MYSQL_USER
--user
(required)
MySQL user
MYSQL_PASSWORD
--password
MySQL password (prefer the env var or --password-file; a flag value is visible in the process list)
MYSQL_PASSWORD_FILE
--password-file
Path to a file holding the password (trailing newline trimmed); cannot be combined with MYSQL_PASSWORD/--password
MYSQL_DATABASE
--database
Default database/schema
MYSQL_SOCKET
--socket
Unix socket path (overrides host/port)
MYSQL_TLS
--tls
false
false, true, skip-verify, or preferred
SSH tunnel (optional)
Setting MYSQL_SSH_HOST enables the tunnel. MySQL host/port are then resolved
from the SSH server's perspective (e.g. keep 127.0.0.1:3306 to reach the
database bound to localhost on the remote host).
Env
Flag
Default
Description
MYSQL_SSH_HOST
--ssh-host
SSH host; enables SSH when set
MYSQL_SSH_PORT
--ssh-port
22
SSH port
MYSQL_SSH_USER
--ssh-user
SSH user
MYSQL_SSH_PASSWORD
--ssh-password
SSH password (optional)
MYSQL_SSH_KEY
--ssh-key
Path to private key
MYSQL_SSH_KEY_PASSPHRASE
--ssh-key-passphrase
Passphrase for the key
MYSQL_SSH_KNOWN_HOSTS
--ssh-known-hosts
~/.ssh/known_hosts
known_hosts file
MYSQL_SSH_INSECURE_HOST_KEY
--ssh-insecure-host-key
false
Skip host key check (insecure)
MYSQL_SSH_AGENT
--ssh-agent
true
Use SSH_AUTH_SOCK when available
Safety / limits
Env
Flag
Default
Description
MYSQL_READONLY
--readonly
true
Reject non read-only statements in mysql_query
MYSQL_ALLOW_USER_DATA
--allow-user-data
false
Allow querying user tables and unmask live statement text
MYSQL_ALLOW_KILL
--allow-kill
false
Register the impactful mysql_kill tool
MYSQL_MAX_ROWS
--max-rows
500
Max rows returned per query
MYSQL_QUERY_TIMEOUT
--query-timeout
30s
Per-query timeout
MYSQL_CONNECT_TIMEOUT
--connect-timeout
10s
Connection timeout
Tool exposure & guardrails
Env
Flag
Default
Description
MYSQL_TOOLSETS
--toolsets
(all)
Comma list of toolsets to enable (all for everything)
MYSQL_TOOLS
--tools
Comma list of individual tools to additionally enable
MYSQL_PRIVILEGE_FILTERING
--privilege-filtering
true
Hide tools the connected user lacks privileges for
MYSQL_SESSION_GUARDRAILS
--session-guardrails
true
Bound each connection with read-only, statement, and lock-wait timeouts
MYSQL_LOCK_WAIT_TIMEOUT
--lock-wait-timeout
10s
Lock-wait timeout applied when guardrails are on
MYSQL_PROMPTS
--prompts
true
Register the investigation runbook prompts
Toolset names are: health, query, processes, locks, innodb,
performance, schema, replication. When --toolsets is empty all of them are
enabled; --tools is additive on top of the selected toolsets.
Use with an MCP client
The server speaks MCP over stdio. Point your client at the built binary and pass
configuration via env.
Grant the database user the minimum needed for diagnostics, typically:
SELECT, PROCESS, REPLICATION CLIENT (and SHOW VIEW for schema inspection).
Tools
All tools are read-only except mysql_kill, which is only registered when
MYSQL_ALLOW_KILL=true.
Connectivity & health
mysql_ping - verify connectivity; report version, user, server time, uptime.
mysql_server_status - curated health dashboard (connections, QPS, buffer
pool hit ratio, temp tables on disk, full scans) with threshold flags.
mysql_health_report - one-shot triage combining the health snapshot,
long-running queries, long-open transactions, lock waits, and replication.
mysql_show_variables - SHOW GLOBAL VARIABLES with an optional LIKE.
mysql_show_status - SHOW GLOBAL STATUS with an optional LIKE.
mysql_error_log - recent server error-log events from
performance_schema.error_log (8.0.22+). filter=corruption (default) surfaces
InnoDB corruption and "page LSN in the future" signals (MY-011971/MY-011972);
filter=errors or all, optionally narrowed by subsystem. Needs SELECT on
performance_schema.error_log.
Sessions, locks & transactions
mysql_processlist - active sessions from the non-locking
performance_schema.processlist (idle hidden by default; filter by time/user).
mysql_connection_summary - activity per user or host (connections,
statements, latency, table scans, file IO) from the sys summary views.
mysql_lock_waits - InnoDB row-lock waits, pairing blocked and blocking
transactions.
mysql_transactions - open InnoDB transactions, oldest first, with age,
rows locked/modified, and current query.
mysql_metadata_locks - metadata locks (MDL) from performance_schema (8.0+).
mysql_wait_events - what each active connection is currently waiting on
(performance_schema.events_waits_current), worst waits first.
mysql_innodb_status - SHOW ENGINE INNODB STATUS, optionally a single
section (deadlock, transactions, buffer-pool, log, ...).
mysql_kill - kill a query or connection. Gated by MYSQL_ALLOW_KILL.
Queries & performance
mysql_query - run a single read-only statement and return a table.
mysql_explain - execution plan for a SELECT (traditional/tree/json,
or EXPLAIN ANALYZE).
mysql_explain_for_connection - plan for the statement already running on
another connection (EXPLAIN FOR CONNECTION); format=json requires
--allow-user-data.
mysql_top_queries - most expensive statement digests by latency, count, or
rows examined.
mysql_table_scans - statement digests doing full table scans.
mysql_io_hotspots - top IO consumers by file or by table (sys views).
mysql_index_usage - unused, redundant, or no-primary-key index reports.
Schema
mysql_databases - databases with sizes and default charset/collation.
mysql_tables - tables in a database with engine, rows, and size.
mysql_describe_table - columns, indexes, foreign keys, and CREATE TABLE.
mysql_largest_tables - largest tables server-wide by data+index size.
Replication
mysql_replication_status - replica IO/SQL thread health and lag, plus the
binary log / primary position.
Toolsets & privilege filtering
Tools are grouped into toolsets so you can expose only what a given client needs.
Restrict them with --toolsets health,locks (or MYSQL_TOOLSETS), and add back
individual tools with --tools mysql_query. The startup banner (on stderr) prints
exactly what was registered.
With --privilege-filtering on (the default), the server probes the connected
user's privileges at connect and hides tools it cannot run: mysql_innodb_status,
mysql_transactions, and mysql_lock_waits need PROCESS;
mysql_replication_status needs REPLICATION CLIENT; the performance,
mysql_processlist, mysql_metadata_locks, and mysql_lock_waits tools need
performance_schema (and mysql_index_usage also needs readable sys views);
mysql_error_log needs SELECT on performance_schema.error_log, which is a
separate grant from the rest of performance_schema. Detection degrades
gracefully: only a genuine access-denied error hides a tool, so a transient
failure never silently drops one.
If filtering is off, or a probe misses an edge case and a tool is still called
without the needed grant, the tool returns the raw MySQL error (for example
Error 1142 ... SELECT command denied ...) plus a short hint naming the missing
privilege, so it is clear what to grant rather than just failing opaquely.
Prompts (investigation runbooks)
When --prompts is on (the default) the server registers MCP prompts that guide
an agent through a read-only investigation using the tools above:
slow_server_triage - triage a server that is slow or overloaded right now.
blocking_locks - trace an InnoDB lock-wait chain to the root blocker.
replication_lag - diagnose why a replica is falling behind its source.
query_tuning - find and tune an expensive query (optional schema argument).
capacity_review - find where space goes and which indexes are wasteful.
Data access policy
By default the server reads only MySQL's own system schemas and never your
application data:
System-schema allowlist.mysql_query and mysql_explain reject any
statement whose table references are not in information_schema,
performance_schema, mysql, or sys. Bare table names resolve against a
system schema, and backtick-quoted, comma-joined, and subquery table refs are
all checked, so SELECT * FROM appdb.customers is refused.
Masked statement text. Live SQL shown by mysql_processlist,
mysql_transactions, mysql_lock_waits, mysql_health_report,
mysql_innodb_status, and replication error fields has its string and numeric
literals replaced with ?, so values like emails or tokens do not leak while
you can still see the query shape and the tables involved. mysql_query also
masks well-known raw-statement columns (info, sql_text, query_sample_text,
argument, ...) in its own results, so a direct SELECT from a
performance_schema events table does not leak literals; the normalized
digest_text is left intact. This column masking is best effort (an alias or
expression can evade it), which is why --allow-user-data remains the real
boundary.
Metadata, not rows. The schema and performance tools report on user tables
using catalog metadata only (names, columns, sizes, normalized digests), never
their row contents.
INTO OUTFILE/INTO DUMPFILE blocked to prevent writing query results to
the server filesystem.
Error-log text is shown verbatim.mysql_error_log returns the data
column from performance_schema.error_log unmasked, because it holds
diagnostic text (LSNs, file paths, object names) rather than query literals,
and masking would destroy the values you need to read. It is gated behind its
own SELECT grant on that table instead.
Set MYSQL_ALLOW_USER_DATA=true (or pass --allow-user-data) only when you
genuinely need to read application data; this lifts the schema allowlist and
disables literal masking. Note that mysql_innodb_status masking covers the
statement text after each thread/query header and the hex/asc record dumps in the
lock sections; InnoDB counters, lock metadata, and table/index names are kept so
the dump stays useful.
Safety model
Read-only classification.mysql_query strips comments and quoted
literals, then requires a single leading read-only verb and rejects embedded
semicolons, so keywords or ; inside strings cannot smuggle writes.
Driver hardening. Multi-statements are disabled and parameters are not
interpolated client-side.
Bounded results. Every query is capped at MYSQL_MAX_ROWS and runs under
the per-query timeout.
Session guardrails. When enabled, each pooled connection is pinned
transaction_read_only (under --readonly) with a max_execution_time equal to
the query timeout and short innodb_lock_wait_timeout/lock_wait_timeout, a
server-enforced backstop independent of the SQL classifier.
Impactful actions are opt-in.mysql_kill is hidden unless explicitly
enabled and is annotated as destructive.
Read-only mode is a guardrail, not a security boundary. Always connect with a
least-privilege database user.
Development
make fmt-check # gofmt
make vet # go vet
make test # unit tests
make build # build the binary
make all # all of the above
Integration tests
The tests in internal/tools/integration_test.go and
internal/tools/integration_features_test.go run the full safety chain, session
guardrails, and privilege filtering against a real server. They skip unless
MYSQL_MCP_INTEGRATION is set, so plain make test never needs a database:
MYSQL_MCP_INTEGRATION=1 MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_USER=root \
go test -run Integration -v ./internal/tools/