just-a-mysql-mcp

Browse MySQL schema and run read-only SQL from your AI agent.

Read-only by design. Tools never INSERT / UPDATE / DELETE / DDL. An agent writing to the wrong table or environment can cause production-level incidents. Just because we can doesn't mean we should. Prefer a MySQL account that is itself read-only.

What it does

• List tables — names in the bound database

• Describe a table — columns and types

• Run a query — one read-only statement (SELECT / WITH…SELECT, SHOW, DESCRIBE/DESC, EXPLAIN), with a hard row cap

One MCP process is bound to one database for its lifetime. Need another database? Add another MCP entry.

Related MCP server: mcp-multi-db

Requirements

• uv — brew install uv

• MySQL 5.7+ / 8.x reachable over TCP

Setup

1. Clone and install

git clone https://github.com/xingyuli/just-a-mysql-mcp
cd just-a-mysql-mcp
uv sync

2. Add to your AI agent

{
  "mcpServers": {
    "mysql": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/just-a-mysql-mcp",
        "run", "mysql_mcp_server.py"
      ],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "readonly_user",
        "MYSQL_PASSWORD": "secret",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Shell exports work too:

"MYSQL_HOST": "${MYSQL_QIMIOLAB_DEV_HOST}",
"MYSQL_USER": "${MYSQL_QIMIOLAB_DEV_USER}",
"MYSQL_PASSWORD": "${MYSQL_QIMIOLAB_DEV_PASSWORD}",
"MYSQL_DATABASE": "qimiolab_uc_dev"

3. Restart the agent and ask things like:

• "What tables are in this database?"

• "Describe the user table"

• "Select the 10 most recent rows from …"

Configuration

Safety summary

Design notes: CONTEXT.md, docs/adr/0001-v1-design.md.

For local development and tests, see DEVELOPMENT.md.