MySQL MCP Server

A comprehensive Model Context Protocol (MCP) server for MySQL database operations with advanced features for database analysis, health monitoring, and AI-assisted database management.

🚀 Features

MySQL MCP Server goes beyond basic CRUD operations, providing powerful database analysis capabilities and an extensible framework for custom tools.

🔌 Transport Modes

• STDIO Mode: Direct integration with MCP clients like Cursor, Cline

• SSE Mode: HTTP-based Server-Sent Events for web applications

🗄️ Database Operations

• Cross-Database Access: Connect once, access all databases without switching connections

• Multi-Statement Execution: Execute multiple SQL statements separated by ";"

• Smart Table Discovery: Find tables by comments and descriptions

• SQL Execution Plan Analysis: Performance optimization insights

🛡️ Security & Permissions

• Role-Based Access Control: Three permission levels (readonly, writer, admin)

• SQL Comment Support: Handles SQL statements with -- and /* */ comments

🔍 Advanced Analysis

• Health Monitoring: Connection, transaction, and lock status analysis

• Performance Insights: Index usage analysis and optimization recommendations

• Lock Detection: Row-level and table-level lock monitoring

• Chinese Text Processing: Pinyin conversion for Chinese field names

🤖 AI Integration

• Prompt Templates: Pre-built AI prompts for database analysis and querying

• Context-Aware Assistance: Intelligent database operation guidance

📋 Permission Levels

🛠️ Available Tools

Database Operations

Schema Discovery

Performance & Health

Utilities

🤖 AI Prompt Templates

🚀 Quick Start

Prerequisites

• Python 3.10+

• UV package manager

• MySQL server

Installation

📦 Installing UV Package Manager

Windows:

Linux/macOS:

🔽 Project Setup

1. Clone and install dependencies:

   Windows (PowerShell):

   git clone <repository-url> cd mcp_mysql uv sync

   Linux/macOS:

   git clone <repository-url> cd mcp_mysql uv sync

2. Configure database connection:

   Create a .env file in the project root directory:

   Windows (PowerShell):

   # Create .env file using PowerShell @" # MySQL Database Configuration MYSQL_HOST=localhost MYSQL_PORT=3306 MYSQL_USER=your_username MYSQL_PASSWORD=your_password # MYSQL_DATABASE=specific_db # Optional: leave empty for cross-database access MYSQL_ROLE=admin # Options: readonly, writer, admin "@ | Out-File -FilePath ".env" -Encoding utf8

   Or manually create

   # MySQL Database Configuration MYSQL_HOST=localhost MYSQL_PORT=3306 MYSQL_USER=your_username MYSQL_PASSWORD=your_password # MYSQL_DATABASE=specific_db # Optional: leave empty for cross-database access MYSQL_ROLE=admin # Options: readonly, writer, admin

   For remote MySQL server (example):

   MYSQL_HOST=192.168.1.100 MYSQL_PORT=3306 MYSQL_USER=root MYSQL_PASSWORD=your_secure_password MYSQL_ROLE=admin

Running the Server

SSE Mode (Web-based)

Windows (PowerShell):

Linux/macOS:

MCP Client Configuration (SSE):

STDIO Mode (Direct integration)

Windows (PowerShell):

Linux/macOS:

MCP Client Configuration (STDIO):

Windows:

Linux/macOS:

🛠️ Windows-Specific Configuration Notes

Common Issues and Solutions

PowerShell Execution Policy: If you encounter execution policy errors, run:

Path Separators:

• Use double backslashes \\ or forward slashes / in JSON configuration

• Example: "C:\\Users\\YourName\\mcp_mysql" or "C:/Users/YourName/mcp_mysql"

Environment Variables in Windows:

Windows Firewall: Ensure MySQL port (default 3306) is allowed through Windows Firewall if connecting to remote MySQL server.

🔧 Extending with Custom Tools

1. Create a new tool class:

   # src/handles/my_custom_tool.py from .base import BaseHandler from mcp.types import Tool, TextContent class MyCustomTool(BaseHandler): name = "my_custom_tool" description = "Description of what this tool does" def get_tool_description(self) -> Tool: # Define tool schema pass async def run_tool(self, arguments: dict) -> list[TextContent]: # Implement tool logic pass

2. Register the tool:

   # src/handles/__init__.py from .my_custom_tool import MyCustomTool __all__ = [..., "MyCustomTool"]

💡 Usage Examples

Cross-Database Operations

List all databases:

Cross-database queries:

Table structure analysis:

AI-Assisted Operations

Performance Analysis:

Health Monitoring:

Smart Table Discovery:

Deadlock Analysis:

📖 Documentation

• Development Guide - For developers working with this codebase

• API Reference - Detailed tool and prompt documentation

🤝 Contributing

1. Fork the repository

2. Create a feature branch

3. Add your custom tools or improvements

4. Submit a pull request

📄 License

This project is open source. Please check the license file for details.

Star this repository if you find it helpful! ⭐