mysql-mcp-plugin

MySQL access for Claude Code. Each user configures their own connections, and each connection grants a specific set of capabilities — so a production replica can be read-only while a scratch database is writable.

Install

/plugin marketplace add <your-github-user>/mysql-mcp-plugin
/plugin install mysql

Nothing to build and no paths to edit: dist/ ships prebuilt and self-contained. Node 20+ on PATH is the only requirement.

Related MCP server: mysql-mcp-webui

Add a connection

/mysql:setup

First time through, that explains the capability model and walks you to your first connection. If you already know how it works, /mysql:add skips straight to it.

You are asked for the name, address, user, database, and which capabilities to grant. You are never asked for the password in the conversation — the command hands you a single line to run yourself, and the CLI prompts for the password on your own terminal, so it never enters the session transcript. It goes into your OS keychain; the config file holds only a reference to it.

Then check the grants line up:

/mysql:test staging-replica

Commands

Capabilities

A connection with no capabilities is revoked: still configured, still credentialed, every query refused.

How enforcement works

1. PreToolUse hook   Claude Code only. Denies before the tool runs, so the model
                     never sees a result. Cannot be bypassed from context.
2. The server        Checks before executing. Works in ANY MCP client, so the
                     guarantee does not depend on Claude Code.
3. MySQL GRANTs      The real security boundary.

Layers 1 and 2 call the same authorize(), so their verdicts cannot drift apart. Layer 2 exists because the server is portable: point Cursor or any other MCP client at dist/index.js and capability checking still applies. The check runs before connecting, so a refused statement costs no handshake and opens no SSH channel.

Layer 3 is the one that actually protects the database. Layers 1 and 2 catch mistakes — a wrong connection name, a model error, something injected into the context — before they reach a database whose GRANTs might be wider than you intended. Give Claude a MySQL account holding only the privileges you are willing for it to have, and treat the capability list as a second pair of eyes rather than the lock.

Both fail closed: unreadable config, unparseable SQL, or anything unclassifiable is refused.

Batches are checked statement by statement. multipleStatements is enabled on the connection, so SELECT 1; DROP TABLE users really would run both — it needs select and drop, and is refused without them.

Connecting through a bastion

Set an ssh block and the plugin opens the tunnel itself — host/port then refer to the database as seen from the bastion:

{
  "version": 1,
  "defaultConnection": "staging-replica",
  "connections": {
    "staging-replica": {
      "host": "db.internal",
      "port": 3306,
      "database": "appdb",
      "user": "claude_ro",
      "password": { "keychain": "staging-replica" },
      "caps": ["select", "schema_read"],
      "ssh": {
        "host": "bastion.example.com",
        "port": 22,
        "user": "you",
        "auth": "agent"
      }
    }
  }
}

The tunnel is passed to the driver as a stream, so no local port is allocated and two people cannot collide on the same forwarded port. auth: "agent" uses SSH_AUTH_SOCK, which means the plugin never holds key material; auth: "key" with privateKeyPath is available where an agent is not.

If you would rather run your own tunnel, point the connection at 127.0.0.1 and set tunnelHint to the command that starts it — connection failures then tell you what to run.

Configuration file

~/.config/claude-mysql/connections.json, override with MYSQL_MCP_CONFIG.

It contains no secrets, so a team can share a skeleton and each member populates their own keychain. Passwords are referenced as { "keychain": "name" } or { "env": "VARNAME" } — the latter for machines without an OS keychain, such as CI.

Tools

Two, unchanged from the pre-plugin server:

• list_servers — configured connections, their capabilities, and the config path

• execute_sql(server?, sql, database?) — run SQL on a connection

Development

npm install
npm run build      # typecheck + bundle to dist/
npm test           # 72 tests

Test coverage: SQL classification (19), authorization decisions (10), hook verdicts (17), the server driven over stdio as a bare MCP client (10), onboarding notices (7), and the plugin manifests (9).

The stdio group verifies the portable guarantee — no Claude Code, no hook, and no database required, since refusals happen before the connection is opened. The manifest group exists because a published version once shipped author as a string instead of an object, which made the plugin uninstallable while every other test passed and CI was green.

Verified against a real environment: /mysql:import migrating connections out of ~/.claude.json, and the keychain write-then-read path via /mysql:list.

Still unverified, because both need a reachable database: a query executing through an SSH tunnel, and /mysql:test's comparison against live SHOW GRANTS output.

dist/ is committed. Bundling (rather than plain tsc) is what makes it self-contained — tsc output would still import mysql2, ssh2, and the MCP SDK at runtime, and node_modules is not shipped. npm run verify-dist checks the committed output matches src/.

Contributing

See CONTRIBUTING.md. One thing to know up front: dist/ is committed, so any src/ change needs npm run build committed alongside it — CI fails otherwise, and the tests alone won't catch it.

Design notes and rationale: docs/specs/.

License

MIT — see LICENSE.