Content
# MySQL Database MCP Service
This is a MySQL database MCP (Model Context Protocol) service specifically designed for Cursor, providing table structure queries, document generation, and data query functionalities.
## Features
- **Cursor Dedicated Integration**: A database service designed specifically for the Cursor MCP protocol
- **Multiple Security Modes**: Supports three security levels: read-only, limited write, and full access
- **Table Structure Query**: Retrieve detailed structure information of database tables
- **Document Generation**: Generate table structure documentation in Markdown, JSON, and SQL formats
- **Database Overview**: Generate an overview document for the entire database
- **SQL Query Execution**: Execute different levels of SQL operations based on the security mode
- **Query Caching**: Automatically cache query results to enhance performance
## Security Modes
### 1. Read-Only Mode (readonly) - Default Mode
- Only allows SELECT, SHOW, DESCRIBE, EXPLAIN, and other query operations
- Prohibits all write and dangerous operations
- Suitable for data analysis and report queries
### 2. Limited Write Mode (limited_write)
- Allows SELECT, INSERT, UPDATE operations
- Prohibits DELETE, DROP, CREATE, ALTER, and other dangerous operations
- Suitable for scenarios requiring data entry while protecting the structure
### 3. Full Access Mode (full_access)
- Allows all SQL operations
- Use with caution, only enable in fully trusted environments
- Suitable for database management and maintenance
## Installation and Configuration
### 1. Local Installation Dependencies
```bash
cd mysql-mcp
pip install -r requirements.txt
```
### 2. Configuration in Cursor
Find the MCP configuration in Cursor settings and add the following content:
```json
{
"mcpServers": {
"mysql-mcp": {
"command": "python",
"args": ["F:/path/to/mysql-mcp/main.py"],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_PORT": "3306",
"MYSQL_USERNAME": "your_username",
"MYSQL_PASSWORD": "your_password",
"MYSQL_DATABASE": "your_database",
"MYSQL_SECURITY_MODE": "readonly",
"MYSQL_ALLOWED_SCHEMAS": "*",
"MYSQL_ENABLE_QUERY_LOG": "false"
}
}
}
}
```
### 3. Environment Variable Description
**Required Environment Variables:**
- `MYSQL_HOST`: Database host address
- `MYSQL_PORT`: Database port
- `MYSQL_USERNAME`: Database username
- `MYSQL_PASSWORD`: Database password
- `MYSQL_DATABASE`: Database name
**Optional Environment Variables:**
- `MYSQL_SECURITY_MODE`: Security mode (readonly/limited_write/full_access, default: readonly)
- `MYSQL_ALLOWED_SCHEMAS`: List of allowed databases, supports three configuration methods:
- `"*"`: Allows access to all authorized databases (recommended)
- `"auto"`: Automatically discovers authorized databases
- `"db1,db2,db3"`: Explicitly specifies a list of databases (comma-separated)
- `MYSQL_CONNECT_TIMEOUT`: Connection timeout (seconds, default: 30)
- `MYSQL_QUERY_TIMEOUT`: Query timeout (seconds, default: 60)
- `MYSQL_MAX_RETRIES`: Maximum retry count (default: 3)
- `MYSQL_ENABLE_QUERY_LOG`: Whether to enable query logging (true/false, default: false)
- `MYSQL_MAX_RESULT_ROWS`: Maximum number of returned rows (default: 1000)
## Usage Examples
### Get Security Information
Enter in Cursor:
```
@mysql-mcp Get current security configuration information
```
### View Accessible Databases
```
@mysql-mcp Get all accessible databases
```
### Query Table List
```
@mysql-mcp List all tables in the mydb database
```
### View Table Structure
```
@mysql-mcp Describe the structure of the users table
```
### Execute Query (Read-Only Mode)
```
@mysql-mcp Query the first 10 records of the users table
```
### Generate Table Documentation
```
@mysql-mcp Generate Markdown documentation for the users table
```
### Generate Database Overview
```
@mysql-mcp Generate overview documentation for the mydb database
```
## Available Tools
| Tool Name | Function Description | Main Parameters |
|-----------|---------------------|-----------------|
| `test_connection` | Test database connection | - |
| `get_security_info` | Get security configuration information | - |
| `list_tables` | Get list of database tables | `database` (optional) |
| `describe_table` | Get detailed structure of a table | `table_name`, `database` (optional) |
| `generate_table_doc` | Generate table documentation | `table_name`, `format`, `database` (optional) |
| `generate_database_overview` | Generate database overview | `database` (optional) |
| `execute_query` | Execute SQL statement | `sql` |
| `list_schemas` | Get list of available databases | - |
## Documentation Generation Instructions
The documentation generation feature will save the generated documents as actual files:
- **Save Location**: `docs/` folder under the mysql-mcp directory
- **File Naming**: `{database}_{table_name}_{timestamp}.{ext}` format
- **Supported Formats**: Markdown (.md), JSON (.json), SQL (.sql)
**Example Output**:
```
✅ Document generation successful!
📁 Save path: docs/mydb_users_20250110_142000.md
📂 MCP service directory: F:/path/to/mysql-mcp
📊 Table name: mydb.users
📝 Format: markdown
⏰ Generation time: 2025-01-10 14:20:00
```
## Cache Management
This service provides query caching functionality, automatically caching results of read-only queries:
```
# Get cache statistics
@mysql-mcp Get query cache statistics
# Clear cache
@mysql-mcp Clear query cache
```
## Security Considerations
1. **Production Environment**: It is recommended to use `readonly` mode
2. **Sensitive Environments**: Avoid using `full_access` mode
3. **Password Security**: Avoid using weak passwords in configurations
4. **Network Security**: Ensure database connections use secure network channels
5. **Least Privilege**: Database users should only be granted the minimum necessary permissions
## Error Handling
- **Configuration Error**: Check the environment variable settings in the Cursor MCP configuration
- **Connection Failure**: Verify database connection parameters and network connectivity
- **Insufficient Permissions**: Check database user permissions and security mode settings
- **SQL Denied**: The current security mode does not allow executing this type of SQL operation
## Technical Architecture
### Core Modules
- `main.py`: MCP service main program
- `config.py`: Environment variable configuration module
- `database.py`: Database operations and security control module
- `document_generator.py`: Document generation module
### Security Control
- Multi-level security mode validation
- SQL statement type checking
- Database access permission control
- Query result row count limitation
- Connection timeout and retry mechanism
### MySQL Adaptation
- Uses mysql-connector-python driver for connection
- Adapts MySQL system table query syntax
- Supports MySQL constraint type recognition
- Adapts MySQL data type mapping
## License
This project is open-sourced under the [MIT License](./LICENSE).
- ✅ **Free to Use**: Allows anyone to use, copy, and modify this software for free
- ✅ **Commercial Friendly**: Supports commercial use and distribution
- ✅ **Modification Freedom**: Can modify the source code and publish derivative works
- ✅ **Minimal Restrictions**: Only requires retaining the copyright notice
---
**Version**: 1.0.0
**Last Updated**: 2025-01-10
**Design Goal**: Optimized for MySQL database and Cursor MCP integration
