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 to execute SQL queries, manage table structures, manipulate data, and more.
## Introduction to MCP Framework
MCP (Model-Control-Panel) is a powerful tool framework that allows you to expose utility functions as APIs, enabling models (such as AI assistants) to directly invoke 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
After the configuration is complete, the Cursor IDE will automatically start the MCP Service without manual intervention. To run it separately:
```bash
python mysql-mcp.py
```
### 3. Calling Utility Functions in the MCP Environment
In the Cursor IDE, the AI assistant can directly call the MySQL MCP tools:
```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 Complex Queries
```python
await mcp_mysql_mcp_execute_query("SELECT * FROM users WHERE age > %s", [18])
```
## Available MCP Tools Functions
### 1. Execute Query: mcp_mysql_mcp_execute_query
```python
# Execute 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": "Zhang San", "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 utility functions will return detailed error messages and cause analysis to facilitate quick identification and resolution of issues:
```python
# Querying a Non-Existing Table
result = await mcp_mysql_mcp_execute_query(query="SELECT * FROM non_existing_table")
# Return: {"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. Make sure 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 .
```
### Other Configuration Methods
In addition to MCP configuration, you can also 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. The main extension points include:
- Adding new utility functions in `mysql-mcp.py`
- Modifying the error handling and return values of existing functions
- Adjusting the default configuration for database connections
## License
[MIT License](LICENSE)
