MySQL MCP Server

How to use

Launch the MCP server and connect your MCP client to perform cross-database queries, health analyses, and AI-assisted operations. You can choose between STDIO mode for direct integration with tools like Cursor and Cline, or SSE mode for a web-based workflow. Use the included tools to list databases, inspect table structures, analyze health and index usage, and convert Chinese field names to pinyin initials. Ensure your client is configured with the correct environment variables and permissions before executing commands.

How to install

Prerequisites before you begin: install Python 3.10 or newer, ensure the UV package manager is available, and have a MySQL server accessible with proper credentials.

# Prerequisites
python3 --version
# Ensure Python 3.10+ is installed

# Install the UV package manager (one of the supported methods shown below)
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

Clone the MCP project and synchronize dependencies, then prepare the environment file with your MySQL connection details.

# Windows (PowerShell)
git clone <repository-url>
cd mcp_mysql
uv sync
```

```bash
# Linux/macOS
git clone <repository-url>
cd mcp_mysql
uv sync

Configure database connection

Create a .env file at the project root with your MySQL connection details. You can provide a specific database or leave it empty for cross-database access. The role determines your permission level for MCP operations.

# 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

Running the server

You have two modes to run the server: SSE (HTTP-based) for web integrations and STDIO for direct, local usage. Start the server in SSE mode to expose an endpoint at a default port for MCP clients.

# SSE mode (Web-based)
uv run server.py
```

```json
{
  "mcpServers": {
    "mysql": {
      "name": "mysql",
      "description": "MySQL database operations",
      "isActive": true,
      "baseUrl": "http://localhost:9000/sse"
    }
  }
}

STDIO mode (Direct integration)

For STDIO mode, you run the server locally and connect via a standard input/output channel. This is useful for tightly coupled tooling that communicates through a process boundary.

# STDIO mode
uv run server.py --stdio
```

```json
{
  "mcpServers": {
    "mysql": {
      "name": "mysql",
      "command": "uv",
      "args": [
        "run", "server.py", "--stdio"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_ROLE": "admin"
      }
    }
  }
}

Security and permissions

The server enforces role-based access control with three permission levels: readonly, writer, and admin. These roles determine which SQL operations you can perform, including data manipulation and DDL actions.

Troubleshooting tips

Ensure the MySQL port is reachable from the server host, verify environment variables in your .env file, and check the server logs for any connection or authentication errors. If you encounter policy or firewall issues, adjust the local firewall rules to allow MySQL traffic and the MCP server port.

Notes on usage patterns

Leverage cross-database access to run queries across multiple databases without switching connections, and use the available tools to analyze health, performance, and lock status across your MySQL environment.

Additional configuration and tools

You can extend the server with custom tools. Define a new tool class, implement your logic, and register it so it appears in your MCP client workflow.

Usage examples

Cross-database operations let you join data across databases without changing connections. You can query table descriptions across databases and run health analytics to spot bottlenecks.

execute_sql

Execute SQL statements with role-based permission control across connected databases.

get_databases

List all available databases excluding system databases to support cross-database workflows.

get_table_desc

Retrieve table structures across databases, supporting the database.table format.

get_table_index

Retrieve table indexes with cross-database support.

get_table_name

Find tables by comments and descriptions to aid discovery.

get_db_health_running

Analyze MySQL health including connections, transactions, and locks.

get_db_health_index_usage

Analyze index usage and provide performance recommendations.

get_table_lock

Detect row-level and table-level locks to identify contention.

get_chinese_initials

Convert Chinese field names to pinyin initials for easier handling.