playbooks
Learn Cursor Rules Windsurf Rules MCPs Modes
Log in

Read MySQL MCP server

Secure read-only MySQL database access to execute queries and analyze data patterns.
Back to servers
Setup instructions
Provider
Ben Borla
Release date
Dec 09, 2024
Language
TypeScript
Package
npm
Stats
61.7K downloads
703 stars
View on GitHub

The MCP Server for MySQL allows Large Language Models (LLMs) to interact with MySQL databases, providing capabilities to inspect database schemas and execute SQL queries. It serves as a bridge between LLMs and your MySQL database through the Model Context Protocol.

Installation Options

Using Claude Code

Option 1: Import from Claude Desktop

If you already have the MCP server configured in Claude Desktop:

claude mcp add-from-claude-desktop

This will display an interactive dialog where you can select the mcp_server_mysql server to import with all existing configuration.

Option 2: Manual Configuration with NPM/PNPM

First, install the package globally:

# Using npm
npm install -g @benborla29/mcp-server-mysql

# Using pnpm
pnpm add -g @benborla29/mcp-server-mysql

Then add the server to Claude Code:

claude mcp add mcp_server_mysql \
  -e MYSQL_HOST="127.0.0.1" \
  -e MYSQL_PORT="3306" \
  -e MYSQL_USER="root" \
  -e MYSQL_PASS="your_password" \
  -e MYSQL_DB="your_database" \
  -e ALLOW_INSERT_OPERATION="false" \
  -e ALLOW_UPDATE_OPERATION="false" \
  -e ALLOW_DELETE_OPERATION="false" \
  -- npx @benborla29/mcp-server-mysql

Using Unix Socket Connection

For local MySQL instances using Unix sockets:

claude mcp add mcp_server_mysql \
  -e MYSQL_SOCKET_PATH="/tmp/mysql.sock" \
  -e MYSQL_USER="root" \
  -e MYSQL_PASS="your_password" \
  -e MYSQL_DB="your_database" \
  -e ALLOW_INSERT_OPERATION="false" \
  -e ALLOW_UPDATE_OPERATION="false" \
  -e ALLOW_DELETE_OPERATION="false" \
  -- npx @benborla29/mcp-server-mysql

Choosing the Right Scope

# Local scope (default) - only available in current project
claude mcp add mcp_server_mysql [options...]

# User scope - available across all your projects
claude mcp add mcp_server_mysql -s user [options...]

# Project scope - shared with team members via .mcp.json
claude mcp add mcp_server_mysql -s project [options...]

For database servers with credentials, local or user scope is recommended to keep credentials private.

Verification

After adding the server, verify it's configured correctly:

# List all configured servers
claude mcp list

# Get details for your MySQL server
claude mcp get mcp_server_mysql

# Check server status within Claude Code
/mcp

Running in Remote Mode

To run in remote mode:

  1. Create an env file in your preferred directory:

    touch .env

  2. Configure your environment variables, setting:

    • MySQL credentials
    • IS_REMOTE_MCP=true
    • REMOTE_SECRET_KEY to a secure string
    • Custom PORT if needed (default is 3000)

  3. Load variables in the current session:

    source .env

  4. Run the server:

    npx @benborla29/mcp-server-mysql

  5. Configure your agent to connect to the MCP with this configuration:

    {
  "mcpServers": {
    "mysql": {
      "url": "http://your-host:3000/mcp",
      "type": "streamableHttp",
      "headers": {
        "Authorization": "Bearer <REMOTE_SECRET_KEY>"
      }
    }
  }
}

Features and Capabilities

Tools

  • mysql_query:
    • Execute SQL queries against the connected database
    • By default, limited to READ ONLY operations
    • Optional write operations when enabled:
      • INSERT: Add new data (requires ALLOW_INSERT_OPERATION=true)
      • UPDATE: Modify existing data (requires ALLOW_UPDATE_OPERATION=true)
      • DELETE: Remove data (requires ALLOW_DELETE_OPERATION=true)
    • Transactions with proper commit/rollback handling
    • Prepared statements for secure parameter handling
    • Configurable query timeouts and result pagination

Resources

The server provides comprehensive database information:

  • Table Schemas:
    • JSON schema information for each table
    • Column names and data types
    • Index information and constraints
    • Foreign key relationships
    • Table statistics and metrics

Configuration

Environment Variables

Basic Connection

  • MYSQL_SOCKET_PATH: Unix socket path for local connections
  • MYSQL_HOST: MySQL server host (default: "127.0.0.1")
  • MYSQL_PORT: MySQL server port (default: "3306")
  • MYSQL_USER: MySQL username (default: "root")
  • MYSQL_PASS: MySQL password
  • MYSQL_DB: Target database name (leave empty for multi-DB mode)

Performance Configuration

  • MYSQL_POOL_SIZE: Connection pool size (default: "10")
  • MYSQL_QUERY_TIMEOUT: Query timeout in milliseconds (default: "30000")
  • MYSQL_CACHE_TTL: Cache time-to-live in milliseconds (default: "60000")

Security Configuration

  • MYSQL_RATE_LIMIT: Maximum queries per minute (default: "100")
  • MYSQL_MAX_QUERY_COMPLEXITY: Maximum query complexity score (default: "1000")
  • MYSQL_SSL: Enable SSL/TLS encryption (default: "false")
  • ALLOW_INSERT_OPERATION: Enable INSERT operations (default: "false")
  • ALLOW_UPDATE_OPERATION: Enable UPDATE operations (default: "false")
  • ALLOW_DELETE_OPERATION: Enable DELETE operations (default: "false")
  • ALLOW_DDL_OPERATION: Enable DDL operations (default: "false")

Advanced Configuration

For more control over the MCP server's behavior:

{
  "mcpServers": {
    "mcp_server_mysql": {
      "command": "/path/to/npx/binary/npx",
      "args": [
        "-y",
        "@benborla29/mcp-server-mysql"
      ],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASS": "",
        "MYSQL_DB": "db_name",
        "PATH": "/path/to/node/bin:/usr/bin:/bin",
        "MYSQL_POOL_SIZE": "10",
        "MYSQL_QUERY_TIMEOUT": "30000",
        "MYSQL_CACHE_TTL": "60000",
        "MYSQL_RATE_LIMIT": "100",
        "MYSQL_MAX_QUERY_COMPLEXITY": "1000",
        "MYSQL_SSL": "true",
        "ENABLE_LOGGING": "true",
        "MYSQL_LOG_LEVEL": "info",
        "MYSQL_METRICS_ENABLED": "true",
        "ALLOW_INSERT_OPERATION": "false",
        "ALLOW_UPDATE_OPERATION": "false",
        "ALLOW_DELETE_OPERATION": "false"
      }
    }
  }
}

Multi-DB Mode

MCP-Server-MySQL supports connecting to multiple databases when no specific database is set. This allows the LLM to query any database the MySQL user has access to.

Enabling Multi-DB Mode

To enable multi-DB mode, simply leave the MYSQL_DB environment variable empty. In multi-DB mode, queries require schema qualification:

-- Use fully qualified table names
SELECT * FROM database_name.table_name;

-- Or use USE statements to switch between databases
USE database_name;
SELECT * FROM table_name;

For multi-database configuration with Claude Code:

claude mcp add mcp_server_mysql_multi \
  -e MYSQL_HOST="127.0.0.1" \
  -e MYSQL_PORT="3306" \
  -e MYSQL_USER="root" \
  -e MYSQL_PASS="your_password" \
  -e MULTI_DB_WRITE_MODE="false" \
  -- npx @benborla29/mcp-server-mysql

Schema-Specific Permissions

For fine-grained control over database operations, you can configure schema-specific permissions:

SCHEMA_INSERT_PERMISSIONS=development:true,test:true,production:false
SCHEMA_UPDATE_PERMISSIONS=development:true,test:true,production:false
SCHEMA_DELETE_PERMISSIONS=development:false,test:true,production:false
SCHEMA_DDL_PERMISSIONS=development:false,test:true,production:false

Troubleshooting

Common Issues

  1. Connection Issues

    • Verify MySQL server is running and accessible
    • Check credentials and permissions
    • Ensure SSL/TLS configuration is correct if enabled

  2. Path Resolution If you encounter an error "Could not connect to MCP server mcp-server-mysql", explicitly set the path of all required binaries:

    {
  "env": {
    "PATH": "/path/to/node/bin:/usr/bin:/bin"
  }
}

    Find your Node.js paths with:

    # For PATH environment variable
echo "$(which node)/../"

# For NODE_PATH environment variable
echo "$(which node)/../../lib/node_modules"

  3. Authentication Issues

    • For MySQL 8.0+, ensure the server supports the caching_sha2_password authentication plugin
    • Check if your MySQL user is configured with the correct authentication method

  4. Module Not Found Error If encountering Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'dotenv', try:

    npx -y -p @benborla29/mcp-server-mysql -p dotenv mcp-server-mysql

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "mcp_server_mysql" '{"command":"npx","args":["-y","@benborla29/mcp-server-mysql"],"env":{"MYSQL_HOST":"127.0.0.1","MYSQL_PORT":"3306","MYSQL_USER":"root","MYSQL_PASS":"your_password","MYSQL_DB":"your_database","ALLOW_INSERT_OPERATION":"false","ALLOW_UPDATE_OPERATION":"false","ALLOW_DELETE_OPERATION":"false"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "mcp_server_mysql": {
            "command": "npx",
            "args": [
                "-y",
                "@benborla29/mcp-server-mysql"
            ],
            "env": {
                "MYSQL_HOST": "127.0.0.1",
                "MYSQL_PORT": "3306",
                "MYSQL_USER": "root",
                "MYSQL_PASS": "your_password",
                "MYSQL_DB": "your_database",
                "ALLOW_INSERT_OPERATION": "false",
                "ALLOW_UPDATE_OPERATION": "false",
                "ALLOW_DELETE_OPERATION": "false"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "mcp_server_mysql": {
            "command": "npx",
            "args": [
                "-y",
                "@benborla29/mcp-server-mysql"
            ],
            "env": {
                "MYSQL_HOST": "127.0.0.1",
                "MYSQL_PORT": "3306",
                "MYSQL_USER": "root",
                "MYSQL_PASS": "your_password",
                "MYSQL_DB": "your_database",
                "ALLOW_INSERT_OPERATION": "false",
                "ALLOW_UPDATE_OPERATION": "false",
                "ALLOW_DELETE_OPERATION": "false"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect

Want to 10x your AI skills?

Get a free account and learn to code + market your apps using AI (with or without vibes!).

Nah, maybe later