A Python Model Context Protocol (MCP) server for inspecting and querying MySQL databases from MCP-compatible clients. It provides table discovery, schema inspection, read query execution, DDL lookup, query explanation, and optional write/DDL tools for controlled database administration workflows.
Features
List tables and describe table schemas
Python MCP server for MySQL database inspection and querying
Optional write and DDL tools for users who intentionally run with elevated database privileges
Safety Model
mysql_execute_read_query only accepts a single statement beginning with SELECT, rejects common modifying SQL keywords and risky file-read/write forms, and caps returned rows by MYSQL_READ_QUERY_LIMIT. This is a guardrail, not a substitute for database permissions. Use a dedicated read-only MySQL user for safe exploration. The write and DDL tools can modify or destroy data if the configured database user is allowed to do so; keep them on manual approval in your MCP client.
Requirements
Python 3.11+
MySQL 5.7+ or MySQL 8.0+
MCP-compatible client such as Claude Desktop, Cursor, VS Code, or another MCP host
Installation
When published to PyPI, install or run the server like a standard Python MCP package:
Copy the example environment file and update it with your database connection details.
cp .env.example .env
Variable
Description
Required
Default
MYSQL_HOST
MySQL host
No
localhost
MYSQL_PORT
MySQL port
No
3306
MYSQL_USER
MySQL username
No
root
MYSQL_PASSWORD
MySQL password
No
Empty
MYSQL_DATABASE
MySQL database name
Yes
Empty
MYSQL_POOL_SIZE
Connection pool size
No
5
LOG_LEVEL
Python logging level
No
INFO
MYSQL_READ_QUERY_LIMIT
Maximum rows returned by read queries
No
1000
Example read-only user:
CREATE USER 'mcp_readonly'@'localhost' IDENTIFIED BY 'change-me';
GRANT SELECT ON your_database.* TO 'mcp_readonly'@'localhost';
FLUSH PRIVILEGES;
Running
mdev-mysql-mcp-server
From a local checkout before PyPI publication, run:
python -m mysql_mcp_server.server
MCP Client Configuration
For published installs, prefer uvx. MCP servers using stdio must write protocol messages only to stdout; this server writes logs to stderr through Python logging.
Claude Desktop / Cursor / Windsurf / Cline
Most MCP clients accept this mcpServers JSON shape:
The mcp-name marker at the top of this README is required for MCP Registry ownership verification. Users should prefer uvx mdev-mysql-mcp-server in local MCP client configurations.
Security Notes
Do not commit .env or MCP client configs containing credentials.
Use least-privilege database users.
Keep execute_write_query and execute_ddl on explicit manual approval.
Do not expose this server over an untrusted network without additional authentication and transport security.