Content
# MySQL MCP Tool
MySQL MCP is a MySQL database operation tool based on the MCP (Model-Control-Panel) framework, providing a simple and easy-to-use API for executing SQL queries, managing table structures, manipulating data, and more.
## Introduction to MCP Framework
MCP (Model-Control-Panel) is a powerful tool framework that allows you to expose tool functions as APIs, enabling models (such as AI assistants) to directly call these functions. MySQL MCP encapsulates MySQL database operations as MCP tools, facilitating integration with tools like Cursor IDE.
## How to Use MCP
### 1. Configure MCP
Add the following configuration to `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"mysql-mcp": {
"command": "/path/to/uv",
"args": [
"--directory",
"/path/to/mysql-mcp",
"run",
"mysql-mcp.py",
"--host", "xxx.xxx.xxx.xxx",
"--port", "3306",
"--user", "root",
"--password", "********",
"--database", "your_database",
"--connection-timeout", "10",
"--connect-retry-count", "3"
]
}
}
}
```
### 2. Start MCP Service
Once configured, Cursor IDE will automatically start the MCP service without manual intervention. To run it separately:
```bash
python mysql-mcp.py
```
### 3. Call Tool Functions in MCP Environment
In Cursor IDE, the AI assistant can directly call the MySQL MCP tool:
```python
# Query all databases
await mcp_mysql_mcp_execute_query("SHOW DATABASES")
# List all tables in the current database
await mcp_mysql_mcp_list_tables()
# Execute a complex query
await mcp_mysql_mcp_execute_query("SELECT * FROM users WHERE age > %s", [18])
```
## Available MCP Tool Functions
### 1. Execute Query: mcp_mysql_mcp_execute_query
```python
# Execute a SELECT query
result = await mcp_mysql_mcp_execute_query(query="SELECT * FROM users WHERE age > %s", params=[18])
# Execute SHOW DATABASES query
result = await mcp_mysql_mcp_execute_query(query="SHOW DATABASES")
# Query result format
# {
# "success": true,
# "rows": [{"id": 1, "name": "张三", "age": 25}, ...],
# "row_count": 10
# }
```
### 2. List Tables: mcp_mysql_mcp_list_tables
```python
# List all tables in the current database
result = await mcp_mysql_mcp_list_tables()
# List all tables in a specific database
result = await mcp_mysql_mcp_list_tables(database_name="information_schema")
# Return result format
# {
# "success": true,
# "database": "your_database",
# "tables": ["users", "products", "orders"],
# "count": 3
# }
```
### 3. Get Table Structure: mcp_mysql_mcp_describe_table
```python
# Get table structure
result = await mcp_mysql_mcp_describe_table(table_name="users")
# Return result format
# {
# "success": true,
# "table": "users",
# "columns": [
# {"Field": "id", "Type": "int(11)", "Null": "NO", "Key": "PRI", "Default": null, "Extra": "auto_increment"},
# {"Field": "name", "Type": "varchar(100)", "Null": "NO", "Key": "", "Default": null, "Extra": ""}
# ]
# }
```
### 4. Switch Database: mcp_mysql_mcp_use_database
```python
# Switch to another database
result = await mcp_mysql_mcp_use_database(database_name="another_database")
# Return result format
# {
# "success": true,
# "message": "Switched to database another_database",
# "current_database": "another_database"
# }
```
### 5. Other Data Operation Tools
- **Create Table**: `mcp_mysql_mcp_create_table(table_name, columns_def)`
- **Insert Data**: `mcp_mysql_mcp_insert_data(table_name, data)`
- **Update Data**: `mcp_mysql_mcp_update_data(table_name, data, condition, params)`
- **Delete Data**: `mcp_mysql_mcp_delete_data(table_name, condition, params)`
## Features
- Execute SQL queries and retrieve results
- List all tables in the database
- Get table structure information
- Create new tables
- Insert, update, and delete data
- Switch databases
- Automatically handle connection errors and retries
- Provide detailed error messages and cause analysis
## Error Handling
All tool functions return detailed error messages and cause analysis for quick problem identification and resolution:
```python
# Query a non-existing table
result = await mcp_mysql_mcp_execute_query(query="SELECT * FROM non_existing_table")
# Returns: {"error": "Query execution failed: Table 'your_database.non_existing_table' doesn't exist\nReason: The queried table does not exist", "query": "SELECT * FROM non_existing_table"}
```
## Installation and Configuration
### Installation
1. Ensure you have Python 3.12 or higher installed.
2. Clone the repository to your local machine:
```bash
git clone https://github.com/Liu-creators/mysql-mcp.git
cd mysql-mcp
```
3. Create and activate a virtual environment:
```bash
python -m venv .venv
source .venv/bin/activate # Use .venv\Scripts\activate on Windows
```
4. Install dependencies:
```bash
pip install -e .
```
### Alternative Configuration Methods
In addition to MCP configuration, you can configure using the following methods:
#### Environment Variables
```bash
export MYSQL_HOST=localhost
export MYSQL_PORT=3306
export MYSQL_USER=root
export MYSQL_PASSWORD=your_password
export MYSQL_DATABASE=your_database
export MYSQL_CONNECTION_TIMEOUT=10
export MYSQL_CONNECT_RETRY_COUNT=3
```
#### Command Line Arguments
```bash
python mysql-mcp.py --host localhost --port 3306 --user root --password your_password --database your_database
```
## Extensions and Customization
You can modify the source code to add more features or adjust the behavior of existing functionalities. Key extension points include:
- Adding new tool functions in `mysql-mcp.py`
- Modifying error handling and return values of existing functions
- Adjusting default configurations for database connections
## License
[MIT License](LICENSE)
