MySQL (security-first)

mcp-server-mysql

English | 简体中文

A security-first MySQL [MCP](https://modelcontextprotocol.io) server. Every SQL statement must survive a full AST parse by an industrial-grade SQL parser (TiDB parser) before it can touch your database — backed by a read-only transaction fallback and a driver-level multi-statement lockout. Three independent layers of defense-in-depth: let AI query your database, without letting it walk off with your database.

Why this one?

Most MySQL MCP servers enforce "read-only" with regex/keyword matching, or by wrapping queries in a read-only transaction. Both are broken:

• Regex checks are defeated by SQL comments and creative rewriting.
• A read-only transaction alone is defeated by COMMIT; DROP TABLE ... stacked-statement injection — the exact attack Datadog demonstrated against the official Postgres reference server, which has since been archived.

This project puts the security boundary on real SQL semantic parsing instead. Every statement is parsed into an AST by the TiDB parser (MySQL 8.0-grammar compatible); anything the parser cannot understand is rejected — fail-closed, so incomplete grammar coverage can only over-block, never under-block. And because the parser sees real MySQL semantics, tricks like hiding a JOIN mysql.user inside a versioned comment /*!80000 ... */ are extracted and checked like any other table reference.

Highlights

• Independent connection profiles — one process manages multiple MySQL connections, each with its own pool, security rules, audit files, and statistics. Discover names and descriptions with list_profile, then pass an explicit profile to every SQL tool.
• Statement-class gating — SELECT / INSERT / UPDATE / DELETE / DDL are individually switchable; the default is read-only. SET, GRANT, CALL, USE, LOAD DATA, LOCK TABLES, and transaction control (BEGIN/COMMIT/ROLLBACK) are rejected unconditionally — classification itself is an allowlist, so unknown statement types land on the deny side by construction.
• Default-deny table whitelist — nothing is visible until whitelisted; patterns like db.*, db.table, app_*.logs (glob per side, case-insensitive). Every table reference is extracted from the AST: JOINs, subqueries, derived tables, CTEs (scope-aware — a CTE name can't shadow a real table to smuggle it past the check), multi-table DML, INSERT ... SELECT, and versioned comments.
• MCP table-schema resources — after the MCP connection initializes, every privilege-visible, whitelisted base table is exposed as mysql:///schema/{profile}/{database}/{table}. Reading a resource returns live SHOW CREATE TABLE SQL with only the volatile table-level AUTO_INCREMENT=N counter removed.
• Execution guardrails — hard row cap, per-query timeout, single-statement enforcement, and a tripwire for UPDATE/DELETE without WHERE.
• Built-in observability — per-query latency and row counts, slow-query flagging, and a mysql_stats tool so you can ask "which query was slowest?" right in the conversation.
• Structured audit, opt-in — JSONL with daily rotation; denied SQL is recorded with the exact rule that fired. Off by default: no log files unless you enable it.
• Atomic scripts — mysql_script runs a multi-statement script in a single transaction with every statement individually re-validated; any failure rolls back everything. DDL is banned inside scripts because MySQL's implicit commit would break atomicity.
• Query-plan analysis — mysql_explain with traditional / json / tree formats and EXPLAIN ANALYZE support.
• Interactive query results — MCP Apps-capable hosts render mysql_query as a filterable, sortable table with per-view history, selection, column controls, and TSV/CSV/JSON copy; other hosts keep receiving the original text result.
• Easy to run, small to trust — a single static Go binary with stdio by default, built on the official MCP Go SDK; the Docker image is distroless and runs as a non-root user.

Tools

All seven mysql_* tools require a non-empty profile string matching a configured name. There is no default connection: missing or unknown profiles are rejected before database access. mysql_describe_table defaults its optional database argument to the selected profile's database.

For example, call list_profile with {}, then mysql_query with {"profile":"dev","sql":"SELECT * FROM myapp.orders LIMIT 10"} or mysql_stats with {"profile":"dev","top_n":5}. Keep the same profile when inspecting, changing, and verifying data.

Resources

The server takes a table snapshot for each profile during MCP initialization/discovery and registers one direct resource per visible base table. Resource names also identify the profile, so identical database and table names on different servers stay distinct:

"Visible" is the intersection of what the profile's MySQL account can see and its security.table_whitelist. Views are not registered. Resource discovery is not capped by security.max_rows, and resource reads remain available even when select is absent from allowed_statements, because both operations execute fixed server-owned metadata SQL rather than user-submitted SQL.

The resource set is a discovery-time snapshot: a table created later appears after the next discovery or reconnect, while a dropped or newly inaccessible table returns MCP Resource Not Found. The resource content is live, so ALTER TABLE is reflected on the next read. Resource discovery and reads do not enter the audit log or mysql_stats; a discovery failure is logged with the profile name and clears only that profile's table resources; other profiles, tools, and the shared query-results App remain available.

The root-level resources.enabled switch applies to every profile. Set it to false to disable the entire resource feature. It defaults to true; when disabled, the server does not advertise Resources, register table or MCP App resources, or query any profile's MySQL during initialization/discovery. The interactive MCP App is therefore unavailable, while all eight tools, including mysql_query's text and structured results, remain available.

Quick start

1. Get the binary

Prebuilt — download the tarball for your platform (linux_amd64 / linux_arm64 / darwin_arm64) from Releases (checksums included), or install with Go:

go install github.com/Kurok1/mcp-server-mysql/cmd/mcp-server-mysql@latest

Docker — multi-arch images are published to GitHub Container Registry:

docker pull ghcr.io/kurok1/mcp-server-mysql:latest

2. Configure

Copy config.example.yaml and adjust:

mkdir -p ~/.mcp-server-mysql

cp config.example.yaml ~/.mcp-server-mysql/config.yaml

A minimal config:

resources:

enabled: true profiles: dev: description: Development database mysql: host: 127.0.0.1 port: 3306 user: mcp_dev # use a dedicated least-privilege account, not root password: ${MYSQL_MCP_PASSWORD} database: myapp

security: allowed_statements: [select] # add insert/update/delete/ddl only if you need them table_whitelist:

• "myapp.*"

Add sibling entries under profiles for other connections; each accepts the same mysql, security, and audit fields. The annotated example includes two profiles. The client examples below use this minimal config; for other configurations, pass every referenced password environment variable to the MCP process.

3. Wire up your MCP client

Claude Code:

claude mcp add mysql --env MYSQL_MCP_PASSWORD=your-password -- \

~/go/bin/mcp-server-mysql --config ~/.mcp-server-mysql/config.yaml

Claude Desktop or any JSON-configured client:

{

"mcpServers": { "mysql": { "command": "/usr/local/bin/mcp-server-mysql", "args": ["--config", "/Users/me/.mcp-server-mysql/config.yaml"], "env": { "MYSQL_MCP_PASSWORD": "..." } } } }

Docker:

{

"mcpServers": { "mysql": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "/Users/me/.mcp-server-mysql:/data", "-e", "MYSQL_MCP_PASSWORD", "ghcr.io/kurok1/mcp-server-mysql:latest", "--config", "/data/config.yaml" ], "env": { "MYSQL_MCP_PASSWORD": "..." } } } }

Docker note 1 — audit logs must live on a mounted volume. The container is destroyed with the session; if you enable audit logging, point audit.log_dir at the mounted volume (e.g. /data/logs) or the logs vanish with the container.

Docker note 2 — reaching MySQL on the host. On macOS/Windows set mysql.host: host.docker.internal; on Linux also append "--add-host=host.docker.internal:host-gateway" to args.

Interactive query results (MCP Apps)

mysql_query advertises the embedded ui://mcp-server-mysql/query-results resource to hosts that support MCP Apps. Successful calls include both the existing human-readable text and structured query data with a required profile field, so older or text-only hosts degrade without losing any result information. Query errors retain their text and carry the original {profile, sql} in result metadata so the App can identify the request. list_profile also returns text and structured data; the six remaining tools use text results.

The result view keeps up to 20 snapshots inside the current View, supports global and optional status filtering, natural numeric sorting, column visibility, row selection, and TSV/CSV/JSON copy. Results and history identify their profile, including failed and cancelled requests. Refresh invokes mysql_query through the host with the selected snapshot's original {profile, sql}, including after switching history; if the host does not expose tool calling to apps, the view explains that refresh is unavailable while all read-only controls continue to work. View history is memory-only and disappe