{
  "markdown": "<!-- mcp-name: io.github.musaddiq-dev/mysql-mcp-server -->\n# MySQL MCP Server\n\nA 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.\n\n## Features\n\n- List tables and describe table schemas\n- Execute SELECT queries with safety checks\n- Retrieve `SHOW CREATE TABLE` output\n- Explain query execution plans\n- Summarize tables and row counts\n- Optional write and DDL tools for users who intentionally run with elevated database privileges\n\n## Safety Model\n\n`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.\n\n## Requirements\n\n- Python 3.11+\n- MySQL 5.7+ or MySQL 8.0+\n- MCP-compatible client such as Claude Desktop, Cursor, VS Code, or another MCP host\n\n## Installation\n\nWhen published to PyPI, install or run the server like a standard Python MCP package:\n\n```bash\nuvx mdev-mysql-mcp-server\n```\n\nFor local development from source:\n\n```bash\ngit clone https://github.com/musaddiq-dev/mysql-mcp-server.git\ncd mysql-mcp-server\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .\n```\n\n## Configuration\n\nCopy the example environment file and update it with your database connection details.\n\n```bash\ncp .env.example .env\n```\n\n| Variable | Description | Required | Default |\n| --- | --- | --- | --- |\n| `MYSQL_HOST` | MySQL host | No | `localhost` |\n| `MYSQL_PORT` | MySQL port | No | `3306` |\n| `MYSQL_USER` | MySQL username | No | `root` |\n| `MYSQL_PASSWORD` | MySQL password | No | Empty |\n| `MYSQL_DATABASE` | MySQL database name | Yes | Empty |\n| `MYSQL_POOL_SIZE` | Connection pool size | No | `5` |\n| `LOG_LEVEL` | Python logging level | No | `INFO` |\n| `MYSQL_READ_QUERY_LIMIT` | Maximum rows returned by read queries | No | `1000` |\n\nExample read-only user:\n\n```sql\nCREATE USER 'mcp_readonly'@'localhost' IDENTIFIED BY 'change-me';\nGRANT SELECT ON your_database.* TO 'mcp_readonly'@'localhost';\nFLUSH PRIVILEGES;\n```\n\n## Running\n\n```bash\nmdev-mysql-mcp-server\n```\n\nFrom a local checkout before PyPI publication, run:\n\n```bash\npython -m mysql_mcp_server.server\n```\n\n## MCP Client Configuration\n\nFor published installs, prefer `uvx`. MCP servers using stdio must write protocol messages only to stdout; this server writes logs to stderr through Python logging.\n\n### Claude Desktop / Cursor / Windsurf / Cline\n\nMost MCP clients accept this `mcpServers` JSON shape:\n\n```json\n{\n  \"mcpServers\": {\n    \"mysql\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mdev-mysql-mcp-server\"],\n      \"env\": {\n        \"MYSQL_HOST\": \"localhost\",\n        \"MYSQL_PORT\": \"3306\",\n        \"MYSQL_USER\": \"mcp_readonly\",\n        \"MYSQL_PASSWORD\": \"change-me\",\n        \"MYSQL_DATABASE\": \"your_database\"\n      }\n    }\n  }\n}\n```\n\nFor local development from this repository, use the installed console script path instead:\n\n```json\n{\n  \"mcpServers\": {\n    \"mysql\": {\n      \"command\": \"/absolute/path/to/mysql-mcp-server/.venv/bin/mdev-mysql-mcp-server\",\n      \"args\": [],\n      \"env\": {\n        \"MYSQL_HOST\": \"localhost\",\n        \"MYSQL_PORT\": \"3306\",\n        \"MYSQL_USER\": \"mcp_readonly\",\n        \"MYSQL_PASSWORD\": \"change-me\",\n        \"MYSQL_DATABASE\": \"your_database\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code CLI\n\n```bash\nclaude mcp add mysql \\\n  --env MYSQL_HOST=localhost \\\n  --env MYSQL_PORT=3306 \\\n  --env MYSQL_USER=mcp_readonly \\\n  --env MYSQL_PASSWORD=change-me \\\n  --env MYSQL_DATABASE=your_database \\\n  -- uvx mdev-mysql-mcp-server\n```\n\n### VS Code MCP\n\nVS Code uses the same command/args/env model in its MCP configuration:\n\n```json\n{\n  \"servers\": {\n    \"mysql\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"mdev-mysql-mcp-server\"],\n      \"env\": {\n        \"MYSQL_HOST\": \"localhost\",\n        \"MYSQL_PORT\": \"3306\",\n        \"MYSQL_USER\": \"mcp_readonly\",\n        \"MYSQL_PASSWORD\": \"change-me\",\n        \"MYSQL_DATABASE\": \"your_database\"\n      }\n    }\n  }\n}\n```\n\n## Tools\n\n| Tool | Purpose | Safety |\n| --- | --- | --- |\n| `mysql_list_tables` | List tables in the configured database | Read-only |\n| `mysql_describe_table` | Show schema for a table | Read-only |\n| `mysql_execute_read_query` | Execute a single bounded SELECT query | Read-only guardrail |\n| `mysql_execute_write_query` | Execute a single INSERT, UPDATE, or DELETE | Destructive |\n| `mysql_execute_ddl` | Execute a single CREATE, DROP, ALTER, or TRUNCATE | Destructive |\n| `mysql_get_table_ddl` | Return `SHOW CREATE TABLE` output | Read-only |\n| `mysql_explain_query` | Run `EXPLAIN` for a single query | Read-only |\n| `mysql_get_database_summary` | Return table list and row counts | Read-only |\n\n## Smoke Check\n\nWithout a database, verify syntax with:\n\n```bash\npython -m py_compile src/mysql_mcp_server/server.py\n```\n\nWith a configured database, start the server and use your MCP client to call `list_tables`.\n\n## Distribution\n\nThis server is published through the standard Python MCP distribution path:\n\n- PyPI package: [`mdev-mysql-mcp-server`](https://pypi.org/project/mdev-mysql-mcp-server/)\n- MCP Registry name: `io.github.musaddiq-dev/mysql-mcp-server`\n- Runtime hint: `uvx`\n- Transport: `stdio`\n\nThe `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.\n\n## Security Notes\n\n- Do not commit `.env` or MCP client configs containing credentials.\n- Use least-privilege database users.\n- Keep `execute_write_query` and `execute_ddl` on explicit manual approval.\n- Do not expose this server over an untrusted network without additional authentication and transport security.\n\n## License\n\nMIT\n",
  "bytes": 6164,
  "sha": "bbd5556a9da1012d7bffe31fd58e9d17efab1a465155586be3be16e2698a1122",
  "repo_slug": "musaddiq-dev/mysql-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_musaddiq_dev_mysql_mcp_server_f967385c/readme"
}