MySQL MCP Server

A Model Context Protocol (MCP) server that enables Claude Code to interact with MySQL databases securely. This server provides tools for database management, querying, and data manipulation while keeping your credentials secure.

Features

• 🔒 Secure credential handling - passwords never exposed to the LLM
• 🗄️ Database management (create, drop, list databases)
• 📊 Table operations (list, describe tables)
• 🔍 Execute SELECT queries with formatted results
• ✏️ Execute INSERT, UPDATE, DELETE operations
• 🌐 Support for remote MySQL servers
• ℹ️ Server information and connection testing

Installation

Prerequisites

• Python 3.7 or higher
• MySQL server (local or remote)
• mysql-connector-python package (install via sudo apt-get install python3-mysql.connector)

Install via AI Coding Assistant CLI

Important: Before using this MCP server, ensure Python dependencies are installed.

Installing Python Dependencies

Option 1: System Package Manager (Recommended)

sudo apt-get install python3-mysql.connector

Option 2: Using Virtual Environment

If you prefer using a virtual environment or encounter issues with system packages:

# Create and activate virtual environment
python3 -m venv ~/mysql-mcp-venv
source ~/mysql-mcp-venv/bin/activate  # On macOS/Linux
# Or on Windows: ~/mysql-mcp-venv\Scripts\activate

# Install dependencies
pip install mysql-connector-python
deactivate

Then install the MCP server using the virtual environment Python (see configuration examples below).

Claude Code

claude mcp add --scope user mysql-mcp npx @davidfei/mysql-mcp

You'll be prompted to enter your MySQL connection details during setup.

Alternatively, you can provide the configuration directly:

claude mcp add --scope user mysql-mcp --env MYSQL_HOST=localhost --env MYSQL_PORT=3306 --env MYSQL_USER=myuser --env MYSQL_PASSWORD=user-password --env MYSQL_ROOT_PASSWORD=root-password --env MYSQL_DATABASE=mydb -- npx @davidfei/mysql-mcp

Codex

Note: This MCP server requires Codex version 0.40.0 (not the latest version).

codex mcp add mysql-mcp --env MYSQL_HOST=localhost --env MYSQL_PORT=3306 --env MYSQL_USER=myuser --env MYSQL_PASSWORD=user-password --env MYSQL_ROOT_PASSWORD=root-password --env MYSQL_DATABASE=mydb -- npx @davidfei/mysql-mcp

Gemini CLI

gemini mcp add mysql-mcp npx @davidfei/mysql-mcp -t stdio -s user -e MYSQL_HOST=localhost -e MYSQL_PORT=3306 -e MYSQL_USER=myuser -e MYSQL_PASSWORD=user-password -e MYSQL_ROOT_PASSWORD=root-password -e MYSQL_DATABASE=mydb

This MCP server works with any MCP-compatible client.

Important: Before configuring any MCP client, ensure Python dependencies are installed.

Installing Python Dependencies

# Option 1: System package manager (recommended)
sudo apt-get install python3-mysql.connector

# Option 2: Virtual environment (if needed)
python3 -m venv ~/mysql-mcp-venv
source ~/mysql-mcp-venv/bin/activate
pip install mysql-connector-python
deactivate

When using a virtual environment, update the command in your MCP configuration to use the venv Python path (e.g., /home/user/mysql-mcp-venv/bin/python instead of python3).

Here are configuration examples for popular clients:

Note: Replace the environment variable values with your actual MySQL connection details. For better security, consider using environment variables instead of hardcoding credentials.

Manual Installation

1. Clone or download this repository

2. Install the Python dependencies:

# Option 1: System package manager (recommended)
sudo apt-get install python3-mysql.connector

# Option 2: Virtual environment
cd mysql-mcp
python3 -m venv venv
source venv/bin/activate
pip install mysql-connector-python
deactivate

3. Make the server executable:

chmod +x mysql-mcp-server.py

4. Configure your MySQL connection via environment variables (see Configuration section)

5. If using virtual environment, use venv/bin/python as the command in your MCP configuration

Configuration

The server uses environment variables for MySQL connection configuration:

• MYSQL_HOST - MySQL server hostname (default: localhost)
• MYSQL_PORT - MySQL server port (default: 3306)
• MYSQL_USER - MySQL username for normal operations (default: root)
• MYSQL_PASSWORD - Password for the normal MySQL user
• MYSQL_ROOT_PASSWORD - MySQL root password (used for administrative operations like creating/dropping databases)
• MYSQL_DATABASE - Default database(s) to use (optional). Can be a single database name or a comma-separated list (e.g., mydb or db1,db2,db3). When multiple databases are specified, the first one is used as the default.
• MYSQL_SSL - Enable SSL/TLS for MySQL connection (optional). Set to true, 1, yes, or enabled to enable SSL. Defaults to disabled for compatibility. Use this when connecting to MySQL servers that require SSL connections.

The server automatically uses root credentials for administrative operations (create/drop database) and normal user credentials for regular operations (queries, updates). If the normal user lacks permissions for a query or update operation, the server will automatically retry with root credentials.

Available Tools

Once installed, Claude Code will have access to these MySQL tools:

1. test_connection

Test the MySQL connection and get server information.

Example: "Test the MySQL connection"

2. get_server_info

Get MySQL server information including version, host, port, and current user.

Example: "Show me the MySQL server information"

3. list_databases

List all databases on the MySQL server.

Example: "List all databases"

4. create_database

Create a new database.

Parameters:

• database_name (required): Name of the database to create

Example: "Create a database called 'myapp'"

5. drop_database

Drop (delete) a database.

Parameters:

• database_name (required): Name of the database to drop

Example: "Drop the database 'old_data'"

Warning: This operation is irreversible!

6. list_tables

List all tables in a database.

Parameters:

• database_name (optional): Name of the database (uses MYSQL_DATABASE env var if not specified)

Example: "List all tables in the 'myapp' database"

7. describe_table

Describe the structure of a table (columns, types, keys, etc.).

Parameters:

• table_name (required): Name of the table to describe
• database_name (optional): Name of the database (uses MYSQL_DATABASE env var if not specified)

Example: "Describe the 'users' table"

8. execute_query

Execute a SELECT query and return results.

Parameters:

• query (required): The SELECT query to execute
• database_name (optional): Name of the database (uses MYSQL_DATABASE env var if not specified)

Examples:

• "Select all users from the users table"
• "Query the products table for items with price > 100"

Note: Only SELECT queries are allowed. Use execute_update for other operations.

9. execute_update

Execute an INSERT, UPDATE, DELETE, or other non-SELECT query.

Parameters:

• query (required): The query to execute
• database_name (optional): Name of the database (uses MYSQL_DATABASE env var if not specified)

Examples:

• "Insert a new user into the users table"
• "Update the price of product with id 5"
• "Delete all orders older than 2020"
• "Create a new table called 'logs'"

Note: Returns the number of affected rows.

Common Use Cases

Database Exploration

You: "List all databases and show me the tables in the 'myapp' database"
Claude: [Uses list_databases, then list_tables with database_name='myapp']

You: "Describe the structure of the 'users' table"
Claude: [Uses describe_table with table_name='users']

Data Querying

You: "Show me all users registered in the last 30 days"
Claude: [Uses execute_query with appropriate SELECT statement]

You: "Find all products with low stock (less than 10 items)"
Claude: [Uses execute_query to find products where quantity < 10]

Data Manipulation

You: "Add a new user with email '[email protected]'"
Claude: [Uses execute_update with INSERT statement]

You: "Update the status of order #12345 to 'shipped'"
Claude: [Uses execute_update with UPDATE statement]

Database Management

You: "Create a new database for my project called 'analytics'"
Claude: [Uses create_database with database_name='analytics']

You: "Create a users table with id, name, email, and created_at columns"
Claude: [Uses execute_update with CREATE TABLE statement]

Security

This tool handles database credentials securely:

• 🔒 Password Protection: MySQL passwords are never exposed to the LLM or logged
• 🛡️ Environment Variables: Credentials stored in environment variables, not in code
• 🔍 Query Separation: SELECT and modification queries are separated for safety
• ⚠️ SQL Injection: Always review queries before execution

Important: Always review what queries Claude suggests before allowing execution.

Connecting to Remote MySQL Servers

This MCP server supports connecting to remote MySQL servers. Simply configure the environment variables with your remote server details:

export MYSQL_HOST=mysql.example.com
export MYSQL_PORT=3306
export MYSQL_USER=myuser
export MYSQL_PASSWORD=user-password
export MYSQL_ROOT_PASSWORD=root-password
export MYSQL_DATABASE=mydb
export MYSQL_SSL=true  # Enable if your server requires SSL

Make sure your MySQL server allows remote connections and your firewall rules permit access.

Troubleshooting

Connection Issues

"Failed to connect to MySQL": Verify your connection details (host, port, username, password) are correct.

"Access denied for user": Check that your MySQL user has the necessary privileges.

"Can't connect to MySQL server": Ensure MySQL server is running and accessible from your machine.

Permission Issues

If you get permission errors, ensure your MySQL user has appropriate privileges:

GRANT ALL PRIVILEGES ON *.* TO 'your_user'@'%' WITH GRANT OPTION;
FLUSH PRIVILEGES;

Python Dependencies

If you get import errors:

# Option 1: System package manager (recommended)
sudo apt-get install python3-mysql.connector

# Option 2: Use virtual environment
python3 -m venv ~/mysql-mcp-venv
source ~/mysql-mcp-venv/bin/activate
pip install mysql-connector-python
deactivate

# Then update your MCP config to use ~/mysql-mcp-venv/bin/python

Limitations

• SQL Injection: While basic safety checks are in place, always review queries
• Large Result Sets: Very large query results may be truncated
• Transaction Support: Currently no explicit transaction management
• Stored Procedures: Limited support for stored procedures and functions

Development

Project Structure

mysql-mcp/
├── mysql-mcp-server.py   # Main MCP server implementation
├── package.json          # NPM package configuration
├── requirements.txt      # Python dependencies
└── README.md            # This file

Testing Locally

1. Set up environment variables:

export MYSQL_HOST=localhost
export MYSQL_PORT=3306
export MYSQL_USER=myuser
export MYSQL_PASSWORD=user-password
export MYSQL_ROOT_PASSWORD=root-password

2. Run the server:

python3 mysql-mcp-server.py

3. Test with MCP protocol messages via stdin

License

MIT

Support

Report issues at: GitLab Issues

Author

David Fei [email protected]

Disclaimer

This tool provides direct access to MySQL databases. Always review queries before execution and ensure you have proper backups. The authors are not responsible for any data loss or damage caused by misuse of this tool.