claude-mcp-mysql by elbosp - MCP Server

Claude MCP MySQL Setup Guide

Overview

Claude MCP MySQL is a Model Context Protocol (MCP) server that enables Claude to interact with MySQL databases. It provides safe DML (Data Manipulation Language) operations while blocking potentially dangerous DDL (Data Definition Language) and DELETE operations by default.

Features

Execute SELECT queries to retrieve data
Execute INSERT queries to add new records
Execute UPDATE queries to modify existing records
Optional DELETE operation support (disabled by default)
Optional DDL operation support (disabled by default)
Database switching support
Environment-based configuration

Prerequisites

Python 3.7+ installed on your system
MySQL Server installed and running
Claude Desktop application
Basic knowledge of MySQL and database operations

Installation

Instalation Hack!

change .env and then tell claude code to:

Execute @prompt.md. Install in user scope/level.

Step 1: Clone the Repository

git clone https://github.com/elbosp/claude-mcp-mysql.git
cd claude-mcp-mysql

Step 2: Install Python Dependencies

pip install mysql-connector-python python-dotenv

Or create a virtual environment first (recommended):

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install mysql-connector-python python-dotenv

Step 3: Configure Database Connection

Copy the .env.example file (or create a new .env file):

cp .env.example .env  # Or create new file

Edit the .env file with your MySQL connection details:

# MySQL Database Configuration
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=your_username
MYSQL_PASSWORD=your_password

# Optional: Specify a default database (leave empty for no default)
MYSQL_DATABASE=your_database

# Security Settings
ALLOW_DELETE=false  # Set to true to enable DELETE operations
ALLOW_DDL=false     # Set to true to enable CREATE, ALTER, DROP operations

Step 4: Configure Claude Desktop

Open Claude Desktop settings
Navigate to the Developer section
Add the MCP server configuration to your settings:

On macOS/Linux:

{
  "mcpServers": {
    "mysql-dml": {
      "command": "/usr/bin/python3",
      "args": ["/path/to/claude-mcp-mysql/mysql_mcp.py"]
    }
  }
}

On Windows:

{
  "mcpServers": {
    "mysql-dml": {
      "command": "C:\\Python3X\\python.exe",
      "args": ["C:\\path\\to\\claude-mcp-mysql\\mysql_mcp.py"]
    }
  }
}

Using Virtual Environment:

{
  "mcpServers": {
    "mysql-dml": {
      "command": "/path/to/claude-mcp-mysql/venv/bin/python",
      "args": ["/path/to/claude-mcp-mysql/mysql_mcp.py"]
    }
  }
}

Restart Claude Desktop to apply the changes

Usage

Once configured, Claude can interact with your MySQL database using natural language. Here are some examples:

Basic Queries

-- View all tables in the current database
SHOW TABLES;

-- Select data
SELECT * FROM users WHERE age > 18;

-- Insert data
INSERT INTO users (name, email, age) VALUES ('John Doe', 'john@example.com', 25);

-- Update data
UPDATE users SET email = 'newemail@example.com' WHERE id = 1;

Working with Multiple Databases

You can switch between databases or specify a database for each query:

# In Claude, you can ask:
"Show me all tables in the database 'myapp'"
"Select all users from the production database"

Security Considerations

Default Security Settings

DELETE operations: Disabled by default
DDL operations (CREATE, ALTER, DROP, TRUNCATE): Disabled by default
Only DML operations (SELECT, INSERT, UPDATE) are allowed

Enabling Additional Operations

To enable DELETE operations, set in .env:

ALLOW_DELETE=true

To enable DDL operations, set in .env:

ALLOW_DDL=true

⚠️ Warning: Enable these features only if you understand the risks. DDL operations can permanently alter your database structure.

Troubleshooting

Connection Issues

Error: "Failed to connect to MySQL"
- Verify MySQL server is running
- Check connection details in .env
- Ensure user has proper permissions
- Test connection using MySQL command line client
Error: "Access denied for user"
- Verify username and password in .env
- Ensure user has necessary privileges:
```
GRANT SELECT, INSERT, UPDATE ON database_name.* TO 'username'@'host';
```
Port Issues
- Default MySQL port is 3306
- Check if port is blocked by firewall
- Verify MySQL is listening on the correct port

MCP Server Issues

Server not appearing in Claude
- Ensure Claude Desktop is restarted after configuration
- Check the path to Python and the script is correct
- Verify Python dependencies are installed
Permission errors
- Ensure the Python script has execute permissions:
```
chmod +x mysql_mcp.py
```

Query Issues

"DDL operations are not allowed"
- This is by design for safety
- Set ALLOW_DDL=true in .env if needed
"DELETE operations are not allowed"
- This is by design for safety
- Set ALLOW_DELETE=true in .env if needed

Development

Testing the Server Locally

You can test the MCP server directly:

# Run the server
python mysql_mcp.py

# Send test commands via stdin (JSON-RPC format)
{"jsonrpc":"2.0","id":1,"method":"initialize"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}

Extending Functionality

The server can be extended by:

Adding new tools in the handle_list_tools method
Implementing new query types
Adding additional security checks
Implementing query logging or auditing

Best Practices

Use Read-Only User: For production, create a MySQL user with minimal required permissions
Backup Data: Always backup your database before allowing write operations
Test First: Test queries in a development environment first
Monitor Activity: Keep logs of database operations
Limit Access: Only enable DELETE and DDL operations when absolutely necessary

Support

For issues, questions, or contributions:

GitHub Repository: https://github.com/elbosp/claude-mcp-mysql
Create an issue for bug reports or feature requests
Submit pull requests for improvements

License

[Add your license information here]

Acknowledgments

Built for use with Claude Desktop and the Model Context Protocol (MCP).