mysql-mcp

Secure, read-only MySQL access for AI agents. A Model Context Protocol (MCP) server that lets Claude, Cursor, and other MCP clients explore and query MySQL/MariaDB databases — with no ability to write, no way to retarget the connection, and no credentials in the model context.

Python (FastMCP) port of @nilsir/mcp-server-mysql, restricted to the read-only tool surface and hardened against the risks of connecting an LLM to a live database.

---

Value proposition

Enterprise data lives in MySQL/MariaDB (application databases, analytics replicas, Amazon RDS/Aurora). mysql-mcp exposes that data to AI agents and analysts for reading only through a zero-trust-oriented interface:

• Read-only by construction — there are no write/DDL tools. The query tool accepts only SELECT/SHOW/DESCRIBE/EXPLAIN and additionally blocks file-I/O and stall primitives (INTO OUTFILE, SLEEP, GET_LOCK, BENCHMARK, LOAD_FILE).
• Credentials never enter the model context — connection details come only from the server's environment; no tool accepts a host, user, or password.
• Fail-closed HTTP — the network transport refuses to start without a bearer token.
• Bounded — per-query time limits, a result-row cap, connect timeouts, and single-statement enforcement.
• Auditable — one structured JSON log record per tool call (never SQL text, values, or credentials).

The read-only scope and these controls answer the audit that drove this port; see SECURITY.md and docs/security/governance.md.

---

Capabilities (9 read-only tools)

Tool	Purpose
query	Run one SELECT/SHOW/DESCRIBE/EXPLAIN statement (with %s bind params)
explain_query	Return the execution plan of a SELECT (traditional or JSON)
list_databases	List databases
list_tables	List tables in a database
describe_table	Column structure of a table
inspect_schema	All tables + columns + indexes of a database at once
find_tables	Find tables by table/column name substring
sample_rows	Small row sample from a table (max 50)
health_check	Connection health + server status

Full request/response schemas and error codes: docs/interface/primitives.md.

Note: this server exposes MCP Tools only. It does not expose MCP Resources or Prompts (see the roadmap notes in docs/interface/primitives.md).

---

Agent Integration Quickstart

First create a least-privilege MySQL account (do not use root):

CREATE USER 'mcp_ro'@'%' IDENTIFIED BY '<strong-secret>';
GRANT SELECT, SHOW VIEW ON app_db.* TO 'mcp_ro'@'%';

Then wire up your client. Ready-to-copy files live in examples/.

Claude Desktop (stdio, run straight from git via uvx)

Requires uv (brew install uv). No clone, no virtualenv — uvx fetches, builds, caches, and runs the mysql-mcp console script. Edit Settings → Developer → Edit Config:

{
  "mcpServers": {
    "mysql": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/<org>/mcp-mysql-server@<tag>",
        "mysql-mcp"
      ],
      "env": {
        "MYSQL_HOST": "your-db-host",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "mcp_ro",
        "MYSQL_PASSWORD": "<strong-secret>",
        "MYSQL_DATABASE": "app_db",
        "MYSQL_SSL": "true"
      }
    }
  }
}

Pin @<tag> (e.g. @v0.1.0) — never track a mutable branch. Running unpinned code straight from git is a supply-chain risk.

Cursor (stdio)

Add to ~/.cursor/mcp.json (or the project .cursor/mcp.json):

{
  "mcpServers": {
    "mysql": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/<org>/mcp-mysql-server@<tag>", "mysql-mcp"],
      "env": {
        "MYSQL_HOST": "your-db-host",
        "MYSQL_USER": "mcp_ro",
        "MYSQL_PASSWORD": "<strong-secret>",
        "MYSQL_DATABASE": "app_db",
        "MYSQL_SSL": "true"
      }
    }
  }
}

Enterprise AI gateway (Streamable HTTP + bearer token)

For a shared, centrally-hosted deployment, run the server in HTTP mode (see docs/setup.md) and point your gateway at it. Credentials for one or more databases are configured server-side via DB_PROFILES; clients select a profile per call with db_id and authenticate with a bearer token:

{
  "mcpServers": {
    "mysql": {
      "type": "http",
      "url": "https://mysql-mcp.internal.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MYSQL_MCP_TOKEN}"
      }
    }
  }
}

Authorization note: the bearer token is a single shared secret; any holder can reach every configured DB_PROFILES profile. Per-client / per-profile authorization is not yet implemented — see docs/security/governance.md (SEC-003).

---

Documentation

Area	Document
Deployment & onboarding	docs/setup.md
MCP contract (tools, schemas, errors)	docs/interface/primitives.md
Transports (stdio vs HTTP)	docs/interface/transport.md
Enterprise governance (authn/authz, privacy, audit)	docs/security/governance.md
Security policy & reporting	SECURITY.md
Contributing & tool-testing standards	CONTRIBUTING.md
Change history	CHANGELOG.md
Working with the codebase (for AI coding agents)	CLAUDE.md

Requirements

• Python ≥ 3.12
• MySQL 5.7+/8.x or MariaDB 10.1+ to connect to
• Docker (optional, for the HTTP container)
• uv (optional, for uvx git-based launch)

License & status

Version 0.1.0. See CHANGELOG.md. [TODO: Insert Organization license and support statement].