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.

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

Variable	Required	Default	Notes
MYSQL_HOST	No	127.0.0.1
MYSQL_PORT	No	3306
MYSQL_USER	Yes
MYSQL_PASSWORD	Yes		Alias: MYSQL_PASS
MYSQL_DATABASE	Yes		Alias: MYSQL_DB

Safety summary

Rule	Behavior
Writes	Rejected by the MCP; use a read-only DB user too
Statements	Exactly one per mysql_query call
Allowlist	SELECT, WITH, SHOW, DESCRIBE/DESC, EXPLAIN
Row cap	Default 100, max 1000; truncation is explicit

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

---

For local development and tests, see DEVELOPMENT.md.