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 claude_desktop_config.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:

{
  "mcpServers": {
    "mysql": {
      "command": "docker",
      "args": [
        "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"
      ]
    }
  }
}

Claude Code

Same shape, in .mcp.json at your project root:

{
  "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"
      }
    }
  }
}

Either form from the Claude Desktop section works here too.

Restart the client once. After that you never need to restart it to change database.

Credentials in these files sit on disk in plain text. Prefer a MySQL account with only SELECT grants, and keep the file out of version control. See Security.

Switching connections

Just ask. These map onto the connection tools:

"switch to the staging database" "what tables are in analytics?" "connect to MySQL on 10.0.0.5 as reporting_user"

sequenceDiagram
    autonumber
    actor You
    participant A as Assistant
    participant S as MCP server
    participant M as MySQL

    You->>A: "how many users in staging?"
    A->>S: use_connection(staging)
    S->>M: open + SELECT 1
    M-->>S: ok
    Note over S: verified, so the switch is committed
    S-->>A: Switched to staging
    A->>S: run_query(SELECT COUNT(*) ...)
    S->>M: SELECT COUNT(*) ...
    M-->>S: 4821
    A-->>You: 4821 users in staging

    You->>A: "and in production?"
    Note over A,S: same session, no restart
    A->>S: use_connection(production)

A switch that fails verification is never committed, so the previous connection stays active and the session keeps working:

sequenceDiagram
    participant S as MCP server
    participant M as MySQL

    S->>M: open "no_such_db" + SELECT 1
    M-->>S: Unknown database
    Note over S: active connection left untouched
    S-->>S: Error: Unknown database 'no_such_db'

Named profiles

Define several connections up front with MYSQL_PROFILES, a JSON object:

{
  "local":   { "host": "host.docker.internal", "user": "root",      "password": "",       "database": "app_dev" },
  "staging": { "host": "db.staging.internal",  "user": "readonly",  "password": "secret", "database": "app" },
  "reports": { "host": "db.staging.internal",  "user": "readonly",  "password": "secret", "database": "analytics" }
}

Passed as a single environment variable:

docker run -i --rm \
  -e MYSQL_PROFILES='{"local":{"host":"host.docker.internal","user":"root","password":"","database":"app_dev"}}' \
  -e MYSQL_DEFAULT_PROFILE=local \
  shibbirweb/mcp-mysql-read-only

host defaults to host.docker.internal, port to 3306, password to empty. user and database are required; a profile missing either is skipped with a warning rather than taking the server down.

Reaching somewhere not in the profiles

The connect tool takes a host, user, password and database at runtime and keeps it for the rest of the session under an alias. Nothing is written to disk, and no restart is involved, so you never have to edit MYSQL_PROFILES just to look at one database once.

Tools

Connection

Reading

Every reading tool also accepts an optional database, applied to that call only, leaving the active connection alone. Useful for comparing two databases without switching back and forth.

use_database, use_connection and connect each open the connection and run SELECT 1 before committing the switch, so a bad database name or unreachable host fails immediately. A failed switch leaves the previous connection active.

Configuration

MYSQL_USER plus MYSQL_DATABASE register a profile named default. None of these are required: with no configuration at all the server still starts, and the tools tell you to call connect.

Starting profile: MYSQL_DEFAULT_PROFILE if it names a real profile, else default, else the first one defined.

Security

Two independent layers keep this read-only, so a hole in one is not automatically a write.