Skip to main content
Glama
mysql-mcp

mysql-mcp

by qxduddes

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.


Related MCP server: mysql-readonly-mcp

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].

Available Tools

9 tools
describe_tableDescribe tableA
Read-only

Get the column structure of a table (DESCRIBE output).

Use this tool when the user asks about a table's columns, types, keys, or defaults. Returns JSON: {table, database, columns: [{Field, Type, Null, Key, Default, Extra}]}.

Presentation: never mention this tool's name to the user or announce that a tool is being called — answer directly with the information.

Preferred rendering — card-based layout: a header card with the table name and a columns table card (name, type, nullable, key, default).

Fallback — Markdown: one-line summary, then a compact Markdown table of the columns.

Formatting rules (both modes): never paste raw JSON unless explicitly asked; highlight primary keys in the summary.

Inputs: table (required), db_id, database. Returns: result

explain_queryExplain query planA
Read-only

Run EXPLAIN on a SELECT query and return the execution plan.

Use this tool when the user asks why a query is slow, whether an index is used, or how MySQL will execute a SELECT. Only SELECT statements are accepted (not SHOW/DESCRIBE/EXPLAIN).

Returns JSON: {format, originalSql, explainSql, rowCount, rows} where rows contain the plan.

Presentation: never mention this tool's name to the user or announce that a tool is being called — answer directly with the analysis.

Preferred rendering — card-based layout: when the client supports rich widgets or HTML artifacts, render a header card with the query, a plan table card (access type, key, rows examined), and a highlights card calling out full scans or missing indexes.

Fallback — Markdown: one-line verdict first (e.g. "uses index X"), then a compact Markdown table of the plan rows.

Formatting rules (both modes): explain the plan in plain language; never paste raw JSON unless explicitly asked.

Inputs: sql (required), db_id, format, params_json. Returns: result

find_tablesFind tablesA
Read-only

Find tables by matching table or column names.

Use this tool when the user knows roughly what they're looking for ("something with customer emails") but not the exact table. Returns JSON: {database, term, matchCount, matches: [{tableName, tableType, engine, matchedTableName, matchedColumns}]}.

Presentation: never mention this tool's name to the user or announce that a tool is being called — answer directly with the information.

Preferred rendering — card-based layout: a header card with the search term and one row per match showing why it matched (name vs columns).

Fallback — Markdown: one-line summary (match count), then a compact Markdown table of matches.

Formatting rules (both modes): never paste raw JSON unless explicitly asked.

Inputs: term (required), db_id, database. Returns: result

health_checkCheck database healthA
Read-only

Check MySQL connection health and basic server status.

Use this tool when the user asks whether the database is reachable, what version it runs, or when queries are unexpectedly failing. Returns JSON: {healthy, pingLatencyMs, serverVersion, uptime, threadsConnected, totalQueries} — or {healthy: false, error} when the server cannot be reached.

Presentation: never mention this tool's name to the user or announce that a tool is being called — answer directly with the status.

Preferred rendering — card-based layout: a status card with a green/red health badge, plus a compact metrics card (latency, version, uptime, connections).

Fallback — Markdown: one-line status first ("healthy, 3 ms latency"), then bold-labeled key metrics.

Formatting rules (both modes): render uptime in human units (days/ hours); never paste raw JSON unless explicitly asked.

Inputs: db_id. Returns: result

inspect_schemaInspect schemaA
Read-only

Inspect all tables, columns, and indexes of a database at once.

Use this tool when the user wants an overview of a whole schema — e.g. to understand an unfamiliar database or plan queries. Returns JSON: {database, tableCount, tables: [{tableName, tableType, engine, rowsEstimate, tableComment, columns, indexes}]}.

Presentation: never mention this tool's name to the user or announce that a tool is being called — answer directly with the information.

Preferred rendering — card-based layout: a header card for the database (table count), then one card per table with its columns and indexes as compact tables.

Fallback — Markdown: one-line summary, then a section per table with Markdown tables for columns/indexes.

Formatting rules (both modes): never paste raw JSON unless explicitly asked; rowsEstimate is approximate — say "about N rows".

Inputs: db_id, database, include_columns, include_indexes. Returns: result

list_databasesList databasesA
Read-only

List all databases visible to the configured MySQL account.

Use this tool when the user wants to know which databases (schemas) exist on the server. Returns JSON: {databases: [...]}.

Presentation: never mention this tool's name to the user or announce that a tool is being called — answer directly with the information.

Preferred rendering — card-based layout: when the client supports rich widgets, render a single card with the database names as a clean list or chips.

Fallback — Markdown: one-line summary (count), then a bulleted list.

Formatting rules (both modes): never paste raw JSON unless explicitly asked; skip MySQL system schemas in the summary unless asked.

Inputs: db_id. Returns: result

list_tablesList tablesA
Read-only

List tables in a database.

Use this tool when the user wants to see what tables exist. Returns JSON: {tables: [...], database}.

Presentation: never mention this tool's name to the user or announce that a tool is being called — answer directly with the information.

Preferred rendering — card-based layout: a header card naming the database and a table-list card.

Fallback — Markdown: one-line summary (database + count), then a bulleted list of tables.

Formatting rules (both modes): never paste raw JSON unless explicitly asked.

Inputs: db_id, database. Returns: result

queryRun read-only SQL queryA
Read-only

Execute a read-only SQL query and return rows as JSON.

Use this tool when the user wants to read data with SQL: filtering, joining, aggregating, or ad-hoc questions the schema tools cannot answer. Only SELECT / SHOW / DESCRIBE / EXPLAIN statements are accepted; INSERT/UPDATE/DELETE/DDL are refused — this server is strictly read-only. File-writing and lock functions (INTO OUTFILE, SLEEP, GET_LOCK, BENCHMARK, LOAD_FILE) are also refused.

Placeholders: use %s (PyMySQL style), not ?, and pass the values as a JSON array in params_json.

Returns JSON: {rows, rowCount, truncated, maxRows}. When truncated is true, the result was capped at maxRows rows.

Presentation: never mention this tool's name to the user or announce that a tool is being called — answer directly with the retrieved data.

Preferred rendering — card-based layout: when the client supports rich widgets or HTML artifacts, render a header card (query intent), a results table card, and a footer card with row count and a truncation notice if applicable.

Fallback — Markdown: one-line summary first, then a compact Markdown table of the rows.

Formatting rules (both modes): human-readable dates and numbers; never paste raw JSON unless explicitly asked; mention truncation when truncated is true; omit internal fields the user did not ask about.

Inputs: sql (required), db_id, params_json. Returns: result

sample_rowsSample table rowsA
Read-only

Read a small sample of rows from a table (capped at 50).

Use this tool to show the user what a table's data looks like without writing SQL — e.g. right after describe_table. Returns JSON: {database, table, limit, rowCount, rows}.

Presentation: never mention this tool's name to the user or announce that a tool is being called — answer directly with the information.

Preferred rendering — card-based layout: a header card naming the table and a results table card with the sampled rows.

Fallback — Markdown: one-line summary, then a compact Markdown table of the rows.

Formatting rules (both modes): human-readable dates and numbers; never paste raw JSON unless explicitly asked; note that this is a sample, not the full table.

Inputs: table (required), db_id, limit, database. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct operation: listing schemas, running SQL, explaining plans, listing tables, describing columns, inspecting full schemas, searching tables, sampling rows, and checking health. The overlapping table-related tools are clearly differentiated by scope and use case.

    Naming Consistency4/5

    Most tools follow a verb_noun pattern (list_tables, describe_table, inspect_schema, sample_rows, explain_query). Two exceptions stand out: 'query' is a bare noun and 'health_check' is a noun_noun compound, breaking the otherwise consistent convention.

    Tool Count5/5

    Nine tools is a well-scoped set for a read-only MySQL server. Every tool covers a distinct need without redundancy or bloat.

    Completeness5/5

    The set covers the full read-only lifecycle: discovery (list_databases, list_tables), schema inspection (describe_table, inspect_schema, find_tables), data access (query, sample_rows), performance analysis (explain_query), and operational status (health_check). No significant gaps exist for the stated purpose.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A lightweight MCP server providing safe, read-only access to MySQL databases. It enables users to query multiple MySQL instances securely while preventing write operations.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Read-only MySQL/MariaDB MCP server for running SELECT queries safely, with automatic read-only enforcement and query limits.
      3
      14 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides read-only access to MySQL databases, enabling schema exploration, table inspection, and safe SELECT query execution via MCP.
      1
      ISC