MySQL MCP Server

Let Claude Code, Claude Desktop, Cursor or any MCP client explore and query a MySQL database, and review its performance, without being able to change it.

• Read-only by design. Every query runs inside START TRANSACTION READ ONLY with max_execution_time, innodb_lock_wait_timeout and a row cap, then rolls back. A statement checker refuses writes, multiple statements, SELECT ... INTO OUTFILE, LOAD DATA, LOAD_FILE(), SLEEP(), locking reads, SET, executable comments (/*! */) and optimizer hints that could switch the limits off, before anything reaches the server.
• Knows your schema. Tables with engine, estimated rows and sizes; columns with types, defaults and comments; primary and foreign keys in both directions; check constraints; indexes with their usage counts; view SQL; sample rows.
• Finds slow spots. explain_query turns EXPLAIN FORMAT=JSON into findings (full scans, unused indexes, filesort, temporary tables) and, with analyze, adds real timings from EXPLAIN ANALYZE. db_health runs 11 checks. top_queries reads the performance_schema statement digests.
• Tested on MySQL 8.0.46 and 8.4.9. Works with any MySQL 8.0+ that accepts a normal connection, including hosted MySQL (RDS, Aurora MySQL, Cloud SQL, Azure, PlanetScale) where your login has the grants below. MariaDB 10.6+ is supported in the code (it uses max_statement_time and ANALYZE FORMAT=JSON) but was not part of the test run.

Python 3.9+ and PyMySQL (pure Python, no client libraries needed):

python3 -m pip install PyMySQL      # or: python3 -m pip install -r requirements.txt

Create a read-only user (recommended; see examples/read_only_user.sql):

CREATE USER 'mcp_reader'@'%' IDENTIFIED BY 'change-me';
GRANT SELECT, SHOW VIEW ON mydb.* TO 'mcp_reader'@'%';
GRANT SELECT ON performance_schema.* TO 'mcp_reader'@'%';   -- optional: db_health, top_queries, index usage
GRANT PROCESS ON *.* TO 'mcp_reader'@'%';                   -- optional: other sessions in long_running

Claude Code

claude mcp add mysql -- python3 /path/to/mysql-mcp-server/server.py --dsn mysql://mcp_reader:PASSWORD@localhost:3306/mydb

Or install the folder as a plugin (.claude-plugin/plugin.json, .mcp.json, skill mysql-analyst) and set MYMCP_DSN in your environment.

Claude Desktop / Cursor: copy examples/configs/claude_desktop_config.json or examples/configs/cursor-mcp.json and fill in the path and connection string.

Connection string: mysql://user:password@host:3306/database. Options after ?: ssl_ca=/path/ca.pem (verified TLS; add ssl_verify=true to check the host name), ssl=true (encrypted, certificate not verified), unix_socket=/path/mysqld.sock, charset=utf8mb4. URL-encode special characters in the password (@ is %40). Several servers: repeat --dsn name=mysql://... (or separate them with spaces in MYMCP_DSN). With no DSN, MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE are used.

Options: --max-rows 200 (cap per query), --timeout 10 (seconds per query), --allow-writes (adds write_query; the skill asks before every write).

./run_tests.sh                                                   # unit tests, no database needed
MYMCP_TEST_DSN=mysql://root:pw@127.0.0.1:3306/ ./run_tests.sh     # + integration tests on a real server
MYMCP_DEMO_DSN=mysql://root:pw@127.0.0.1:3306/ ./demo.sh          # MCP session on a fictional shop

The integration tests and the demo recreate database demo_shop (the tests also create user mcp_test_reader). Use a scratch server.

• The model writes the SQL. Check the query it shows you before acting on a number.
• Read-only means *this server* won't change data. Use a read-only user as well; the server warns when the login has write or FILE privileges.
• max_execution_time applies to SELECT statements; SHOW and DESCRIBE are not time-limited by MySQL.
• explain_query with analyze: true really runs the query (inside a read-only transaction, with the time limit).
• Row counts in list_tables are InnoDB estimates, and index usage and statement statistics reset when the server restarts; check replicas separately before dropping an "unused" index.
• top_queries and parts of db_health need performance_schema (on by default in MySQL 8).
• Not a migration tool, an ORM or a backup tool.