Content
mysql-mcp-pro
> 🇺🇸 [English version available here](README.en.md)
[](LICENSE)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io)
A production-grade **MySQL MCP Server**, enabling AI assistants (Claude Desktop / WorkBuddy / Cursor / Cline, etc.) to operate MySQL databases securely and efficiently through a standardized protocol.
## ✨ Why Choose mysql-mcp-pro?
Compared to other MySQL MCP implementations in the community, this project offers a more comprehensive set of capabilities:
| Feature | mysql-mcp-pro | Others |
|------|:---:|
| Connection Pool (reduce handshake overhead) | ✅ | ❌ |
| Transaction Support (begin/commit/rollback) | ✅ | ❌ |
| Automatic EXPLAIN Interpretation | ✅ | ❌ |
| Result Export to CSV/JSON (Excel-friendly BOM) | ✅ | ❌ |
| ER Relationship Data (nodes/edges) | ✅ | Few |
| View / Stored Procedure / Function / Trigger Browsing | ✅ | Few |
| Query History & Audit Log | ✅ | ❌ |
| MCP Prompts Templates (generate/optimize/compare/overview) | ✅ | ❌ |
|ading (read-only/DDL/dangerous statements/timeout/row limit/parameterization) | ✅ | Basic |
| Multi-Transmission Modes (stdio / streamable-http) | Partial |
## 🚀 Quick Start
### 1. Installation
```bash
# From source (recommended to clone and then use)
git clone https:///CCCT173/mysql-mcp-pro.git
cd mysql-mcp-pro
pip install -e .
# Or from PyPI (to be released)
pip install mysql-mcp-pro
```
### 2. Configure Environment Variables
Copy `.env.example` to `.env` and edit:
```env
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database
READ_ONLY=false # Read-only modeLOW_DDL=false #/ALTER/DROP
MAX_RESULT_ROWS=1000 # Maximum rows returned per query
QUERY_TIMEOUT=30 # Query timeout (seconds)
POOL_SIZE=5
AUDIT_LOG=true # Audit log
EXPORT_DIR=./exports # Export directory
```
### 3. Register in Your MCP Client
#### WorkBuddy
Edit `~/.workbuddy/mcp.json`:
```json
{
"mcpServers": {
"mysql": {
"command": "python",
"args": ["-m", "server"],
"cwd": "D:/path/to/mysql-mcp-pro",
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASSWORD": "your_password",
"MYSQL_DATABASE": "your_database"
}
}
}
}
```
Or if you have already `pip install -e .`:
```json
{
cpServers": {
"mysql": {
"command": "mysql-mcp-pro",
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_PORT": "3306 "MYSQL_USER": "root",
MYSQL_PASSWORD":_password",
"MYSQL_DATABASE": "your }
}
}
```
#### Claude Desktop
Edit `~/ Support/Claude_desktop_configmacOS) or `%APPDATAaude/claude_des` (Windows
{
cpServers": {
mysql": {
"command": "mysql-mcp-pro",
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASSWORD": "your_password",
"MYSQL_DATABASE": "your_database",
"READ_ONLY": "true"
}
}
}
}
```
#### Cursor / Cline
Create `.cursor/mcp.json` in the project root directory (Cursor) or add in Cline settings, with the same format.
## 🛠 Tool List
### Connection & Status
- **` Test connection, return server version and connection pool status
- **`get_server_status`** — MySQL key metrics ( QPS, slow queries, traffic, etc.)
### Metadata Browsing
- **`list_databases`** — List all databases (distinguish databases)
- **`list_tables`** — List tables, including engine, row count, size, and comments
- **`describe_table`** — Table structure: columns keys, indexes,, and create- **` — List- **`list_ro`** — List stored procedures/functions
- **`iggers`** — List triggers **``** — Cross key relationships ( edges) for ER diagram drawing
Execution
- **`execute_query`** — SQL (readL, constrained by security policies), supporting parameterization
- **`execute_select`**-only SELECT (even if configuration is incorrect, only allows reading)
- **`get_table_data`** — Quick data retrieval: columns / where / order_by / limit / offset
- **`count_rows`** — Count rows (supporting optional WHERE)
### Analysis & Export
- **`explain_query`** — `EXPLAIN` execution plan insights in **`export — Export resultsUTF-8 BOM, Excel-friendly) or JSON files
- **`list_query_history`** — for this session (time consumption / row)
### Transactions
- **`begin_transaction`** — Start a transaction, returning session_id
- **`commit — Commit a transaction
- **`rollback_transaction`** — Roll back
### Monitoring
- **`show`** — Current list
kill_query`** specified process (requires SUPER privilege)
### MCP Resources (4)
-://databases` — Database list
- `tables/{database}` — Table list
mysql://schema}/{table}` structure
- `mysql://database}` — ER relationship### MCP Prom4 templates)
- **`generate_query`** — from natural language information
- **``** — Analyze existing SQL performance
- **`compare_schema`** structure differences between two- **`database_summary`** overview report
## 🔒 Security Model
```
Dangerous statements (GRANT/REVOKE/SHUTDOWN/KILL/FLUSH/RESET) → Always forbidden
DDL (CREATE/ALTER/DROP/RENAME/TRUNCATE) → Controlled by ALLOW_DDL
WriteINSERT/UPDATE/DELETE) → Controlled by READ_ONLY
ReadSELECT/SHOWCRIBE/) → Always allowed
```
- Parameter with `%s prevent SQL injection
- Default result of 100 prevent excessive data- Server-side `MAX_EXECUTION_TIME` enforces query timeout executed SQLexports/audit## 📁 Project```
mysql-mcp-pro/
├── server.py # MCPconnection pool / transactions / export / audit)
├── py # Package entry point mysql-pro
├── .env.example # Environment variable├── LICENSE # MIT
├── README.md / README.en.md
└── scripts/
├── setup.py # Create (mcp_test, users + orders tables with foreign keys)
_v2.py # 53 └── diag.py # My diagnosis tool
```
## 🧪 Local Testing
```bash
# 1. Create a sample database (mcp_test, users + orders tables with foreign keys)
python_test_db.py
# 2. Run full regression tests
python scripts/test_v2.py
# → 53 passed, 0 failed
```
## Feel raise issues and PRs! Please ensure:
1. come with test. All existing tests pass
3. existing code style
📄 License
LICENSE)
