MySQL (read-only, switchable) MCP server

mcp-mysql-read-only

An MCP server that gives an AI assistant read-only access to MySQL, and lets it change database, server and credentials mid-conversation without restarting the client.

Most MySQL MCP servers read their connection from environment variables once at startup. Pointing one at a different database means editing a config file and restarting the assistant, which loses your conversation. This server keeps the connection as runtime state, so switching is just another tool call.

Runs from npm with npx, or entirely in Docker with nothing installed on your machine.

flowchart LR
    A["AI assistant<br/>Claude Desktop / Claude Code"]
    B["mcp-mysql-read-only<br/>one process, whole session"]
    C[("app_dev")]
    D[("staging")]
    E[("analytics")]
    F[("any server<br/>reached with connect")]

    A <-->|"MCP over stdio"| B
    B -.->|"pooled per target"| C
    B -.->|"pooled per target"| D
    B -.->|"pooled per target"| E
    B -.->|"opened at runtime"| F

The server lives for the whole session, so the active connection is just state inside it. Switching selects a different pool rather than reconnecting, and switching back reuses a warm one.

Quick start

Two ways to run it. npm is the shorter setup; Docker keeps the server inside a container.

npm

MYSQL_HOST=127.0.0.1 \
MYSQL_USER=readonly \
MYSQL_PASSWORD=secret \
MYSQL_DATABASE=my_database \
npx -y @shibbirweb/mcp-mysql-read-only

Requires Node 22 or newer. There is no container in the way, so 127.0.0.1 means what you expect.

Docker

docker run -i --rm \
  --add-host host.docker.internal:host-gateway \
  -e MYSQL_HOST=host.docker.internal \
  -e MYSQL_USER=readonly \
  -e MYSQL_PASSWORD=secret \
  -e MYSQL_DATABASE=my_database \
  shibbirweb/mcp-mysql-read-only

Use host.docker.internal to reach a MySQL running on the same machine as Docker. Inside the container, localhost means the container itself.

The container is the more isolated of the two: the server runs with only what the image and the environment give it. Over npm it runs directly on your machine with your user's access. Both enforce the same read-only guarantee.

Claude Desktop

Add to claudedesktopconfig.json:

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@shibbirweb/mcp-mysql-read-only"],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_USER": "readonly",
        "MYSQL_PASSWORD": "secret",
        "MYSQL_DATABASE": "my_database"
      }
    }
  }
}

Or the same server in Docker:

Shortened. The full README is on GitHub.