mysql-mcp
Provides secure, read-only access to MySQL databases, enabling query execution, schema exploration, query plan explanation, and data sampling.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mysql-mcp show me the tables in the inventory database"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
querytool accepts onlySELECT/SHOW/DESCRIBE/EXPLAINand 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 |
| Run one |
| Return the execution plan of a |
| List databases |
| List tables in a database |
| Column structure of a table |
| All tables + columns + indexes of a database at once |
| Find tables by table/column name substring |
| Small row sample from a table (max 50) |
| 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_PROFILESprofile. Per-client / per-profile authorization is not yet implemented — see docs/security/governance.md (SEC-003).
Documentation
Area | Document |
Deployment & onboarding | |
MCP contract (tools, schemas, errors) | |
Transports (stdio vs HTTP) | |
Enterprise governance (authn/authz, privacy, audit) | |
Security policy & reporting | |
Contributing & tool-testing standards | |
Change history | |
Working with the codebase (for AI coding agents) |
Requirements
Python ≥ 3.12
MySQL 5.7+/8.x or MariaDB 10.1+ to connect to
Docker (optional, for the HTTP container)
uv(optional, foruvxgit-based launch)
License & status
Version 0.1.0. See CHANGELOG.md. [TODO: Insert Organization license and support statement].
Available Tools
9 toolsdescribe_tableDescribe tableARead-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 planARead-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 tablesARead-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 healthARead-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 schemaARead-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 databasesARead-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 tablesARead-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 queryARead-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 rowsARead-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
Scored across 9 tools
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.
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.
Nine tools is a well-scoped set for a read-only MySQL server. Every tool covers a distinct need without redundancy or bloat.
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
Related MCP Connectors
Guard AI agents' PostgreSQL/MySQL access via MCP: SQL audit, auth, masking, write approval
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Draxlr's remote MCP server connects AI assistants to your SQL databases and dashboards. Explore schemas, run read-only queries, manage saved queries and dashboards, and export results, all with row-level security so each user sees only their own data.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA 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
- AlicenseNot gradedqualityDmaintenanceRead-only MySQL MCP server for safe schema inspection and SELECT-style queries.11 npmMIT
- AlicenseAqualityCmaintenanceRead-only MySQL/MariaDB MCP server for running SELECT queries safely, with automatic read-only enforcement and query limits.314 npmMIT
- AlicenseNot gradedqualityDmaintenanceProvides read-only access to MySQL databases, enabling schema exploration, table inspection, and safe SELECT query execution via MCP.1ISC