mysql-mcp-server

A Model Context Protocol (MCP) server that lets an MCP client (Claude Desktop, Claude Code, etc.) run SQL against a MySQL database through four tools: select, insert, update, and delete.

The server runs as a uv-managed Python package and communicates with the client over stdio, as a subprocess started by the client.

Requirements

Python 3.11+
uv
A reachable MySQL server

Installation

uv sync

Configuration

The server requires six values, each settable via environment variable and/or CLI flag (CLI flags take priority over environment variables):

Parameter	Env var	CLI flag	Required	Default
Mode	`MYSQL_MODE`	`--mysql-mode`	yes	— (`readonly` or `readwrite`)
Host	`MYSQL_HOST`	`--mysql-host`	yes	—
Port	`MYSQL_PORT`	`--mysql-port`	no	`3306`
User	`MYSQL_USER`	`--mysql-user`	yes	—
Password	`MYSQL_PASSWORD`	`--mysql-password`	yes	—
Database	`MYSQL_DATABASE`	`--mysql-database`	yes	—

If a required value is missing, or MYSQL_MODE is not readonly/readwrite, the server prints an error to stderr and exits with status code 1 without starting.

readonly mode: only the select tool is allowed. insert/update/delete are rejected with a PERMISSION_DENIED error.
readwrite mode: all four tools are allowed.

The mode is fixed for the lifetime of the process; it cannot be changed at runtime.

Security recommendation: readonly mode is an application-level guard, not a substitute for database privileges. Where possible, point readonly mode at a MySQL account that only has SELECT grants.

Is a .env file required? No. The server itself never reads .env files — it only reads CLI flags and real process environment variables (os.environ). How you get values into that environment depends on how you run it:
As an MCP server (see Connecting from an MCP client below): the client (Claude Desktop/Code) spawns the server process and injects the env block from its own JSON config directly as environment variables. No .env file is involved or needed.
Running the CLI directly for local dev/testing: .env is just a convenience so you don't have to export six variables by hand. Copy .env.example to .env, fill in real values, and load it explicitly — it is not read automatically:
uv run --env-file .env mysql-mcp-server
.env is git-ignored and must never be committed.

Running

# Environment variables (or use `uv run --env-file .env mysql-mcp-server`, see above)
export MYSQL_MODE=readonly
export MYSQL_HOST=127.0.0.1
export MYSQL_PORT=3306
export MYSQL_USER=app_user
export MYSQL_PASSWORD=secret
export MYSQL_DATABASE=mydb
uv run mysql-mcp-server

# Or, equivalently, via CLI flags
uv run mysql-mcp-server \
  --mysql-mode readonly \
  --mysql-host 127.0.0.1 \
  --mysql-port 3306 \
  --mysql-user app_user \
  --mysql-password secret \
  --mysql-database mydb

Connecting from an MCP client

Claude Desktop / Claude Code

Add an entry to your MCP client's server config (e.g. Claude Desktop's claude_desktop_config.json, or .mcp.json for Claude Code):

{
  "mcpServers": {
    "mysql": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mysql-mcp-server",
        "run",
        "mysql-mcp-server"
      ],
      "env": {
        "MYSQL_MODE": "readonly",
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "app_user",
        "MYSQL_PASSWORD": "secret",
        "MYSQL_DATABASE": "mydb"
      }
    }
  }
}

Restart the client after editing the config. The select, insert, update, and delete tools (subject to MYSQL_MODE) should then be available to the model.

Tools

All four tools take {"query": string, "params"?: array} and always use %s parameter-binding placeholders in query — never string-format user input into a query.

Tool	Allowed in	Query must start with	Success `data` shape
`select`	any mode	`SELECT` / `WITH`	`{rows, row_count, truncated}` (capped at 1000 rows)
`insert`	`readwrite` only	`INSERT`	`{affected_rows, last_insert_id}`
`update`	`readwrite` only	`UPDATE`	`{affected_rows}` (+ `warning` if no `WHERE`)
`delete`	`readwrite` only	`DELETE`	`{affected_rows}` (+ `warning` if no `WHERE`)

Every tool call returns one of:

{ "success": true, "data": { ... } }

{ "success": false, "error": { "code": "...", "message": "..." } }

Error codes: PERMISSION_DENIED, INVALID_QUERY_TYPE, MULTI_STATEMENT_NOT_ALLOWED, DB_CONNECTION_ERROR, DB_EXECUTION_ERROR, INTERNAL_ERROR.

Multi-statement queries (;-separated) and any DDL/privilege statement (DROP, TRUNCATE, ALTER, GRANT, CREATE USER, ...) are always rejected, since only the four whitelisted statement types above are ever accepted.

Development

uv sync
uv run ruff format .
uv run ruff check .
uv run pytest -v
uv run uv build   # packaging check

Troubleshooting

Server exits immediately with status 1: a required MYSQL_* value is missing or MYSQL_MODE is invalid — check stderr for which one.
DB_CONNECTION_ERROR: MySQL is unreachable, or the credentials are wrong. The server keeps running and will retry the connection on the next tool call.
PERMISSION_DENIED on insert/update/delete: the server is running in readonly mode; restart it with MYSQL_MODE=readwrite if writes are intended.

Version history

0.1.0 — Initial release: select/insert/update/delete tools, readonly/ readwrite mode policy, stdio MCP transport, automatic reconnect-and-retry on lost connections.