MCP Server for MySQL - Claude Code Edition

🚀 This is a modified version optimized for Claude Code with SSH tunnel support
Original Author: @benborla29
Original Repository: https://github.com/benborla/mcp-server-mysql
License: MIT

MCP Server for MySQL based on NodeJS

Key Features of This Fork

• ✅ Claude Code Integration - Optimized for use with Anthropic's Claude Code CLI
• ✅ SSH Tunnel Support - Built-in support for SSH tunnels to remote databases
• ✅ Auto-start/stop Hooks - Automatic tunnel management with Claude start/stop
• ✅ DDL Operations - Added MYSQL_DISABLE_READ_ONLY_TRANSACTIONS for CREATE TABLE support
• ✅ Multi-Project Setup - Easy configuration for multiple projects with different databases

Quick Start for Claude Code Users

1. Read the Setup Guide: See PROJECT_SETUP_GUIDE.md for detailed instructions
2. Configure SSH Tunnels: Set up automatic SSH tunnels for remote databases
3. Use with Claude: Integrated MCP server works seamlessly with Claude Code

A Model Context Protocol server that provides access to MySQL databases through SSH tunnels. This server enables Claude and other LLMs to inspect database schemas and execute SQL queries securely.

Table of Contents

• Requirements
• Installation
  • Smithery
  • Clone to Local Repository
  • Remote mode
• Components
• Configuration
• Environment Variables
• Multi-DB Mode
• Schema-Specific Permissions
• Testing
• Troubleshooting
• Contributing
• License

Requirements

• Node.js v20 or higher
• MySQL 5.7 or higher (MySQL 8.0+ recommended)
• MySQL user with appropriate permissions for the operations you need
• For write operations: MySQL user with INSERT, UPDATE, and/or DELETE privileges

Installation

Using Smithery

There are several ways to install and configure the MCP server but the most common would be checking this website https://smithery.ai/server/@benborla29/mcp-server-mysql

Cursor

For Cursor IDE, you can install this MCP server with the following command in your project:

1. Visit https://smithery.ai/server/@benborla29/mcp-server-mysql
2. Follow the instruction for Cursor

MCP Get provides a centralized registry of MCP servers and simplifies the installation process.

Codex CLI

Codex CLI installation is similar to Claude Code below

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

Claude Code

Option 1: Import from Claude Desktop (Recommended if already configured)

If you already have this MCP server configured in Claude Desktop, you can import it automatically:

claude mcp add-from-claude-desktop

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

Option 2: Manual Configuration

Using NPM/PNPM Global Installation:

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 Local Repository (for development):

If you're running from a cloned repository:

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" \
  -e PATH="/path/to/node/bin:/usr/bin:/bin" \
  -e NODE_PATH="/path/to/node/lib/node_modules" \
  -- /path/to/node /full/path/to/mcp-server-mysql/dist/index.js

Replace:

• /path/to/node with your Node.js binary path (find with which node)
• /full/path/to/mcp-server-mysql with the full path to your cloned repository
• Update MySQL credentials to match your environment

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

Consider which scope to use based on your needs:

# 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

Multi-Database Configuration

For multi-database mode, omit the MYSQL_DB environment variable:

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

Advanced Configuration

For advanced features, add additional environment variables:

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 MYSQL_POOL_SIZE="10" \
  -e MYSQL_QUERY_TIMEOUT="30000" \
  -e MYSQL_CACHE_TTL="60000" \
  -e MYSQL_RATE_LIMIT="100" \
  -e MYSQL_SSL="true" \
  -e ALLOW_INSERT_OPERATION="false" \
  -e ALLOW_UPDATE_OPERATION="false" \
  -e ALLOW_DELETE_OPERATION="false" \
  -e MYSQL_ENABLE_LOGGING="true" \
  -- npx @benborla29/mcp-server-mysql

Troubleshooting Claude Code Setup

1. Server Connection Issues: Use /mcp command in Claude Code to check server status and authenticate if needed.

2. Path Issues: If using a local repository, ensure Node.js paths are correctly set:

   # Find your Node.js path
   which node
   
   # For PATH environment variable
   echo "$(which node)/../"
   
   # For NODE_PATH environment variable
   echo "$(which node)/../../lib/node_modules"
   

3. Permission Errors: Ensure your MySQL user has appropriate permissions for the operations you've enabled.

4. Server Not Starting: Check Claude Code logs or run the server directly to debug:

   # Test the server directly
   npx @benborla29/mcp-server-mysql
   

Using NPM/PNPM

For manual installation:

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

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

After manual installation, you'll need to configure your LLM application to use the MCP server (see Configuration section below).

Running from Local Repository

If you want to clone and run this MCP server directly from the source code, follow these steps:

1. Clone the repository

   git clone https://github.com/benborla/mcp-server-mysql.git
   cd mcp-server-mysql
   

2. Install dependencies

   npm install
   # or
   pnpm install
   

3. Build the project

   npm run build
   # or
   pnpm run build
   

4. Configure Claude Desktop

   Add the following to your Claude Desktop configuration file (claude_desktop_config.json):

   {
     "mcpServers": {
       "mcp_server_mysql": {
         "command": "/path/to/node",
         "args": [
           "/full/path/to/mcp-server-mysql/dist/index.js"
         ],
         "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",
           "PATH": "/path/to/node/bin:/usr/bin:/bin", // <--- Important to add the following, run in your terminal `echo "$(which node)/../"` to get the path
           "NODE_PATH": "/path/to/node/lib/node_modules" // <--- Important to add the following, run in your terminal `echo "$(which node)/../../lib/node_modules"`
         }
       }
     }
   }
   

   Replace:

   • /path/to/node with the full path to your Node.js binary (find it with which node)
   • /full/path/to/mcp-server-mysql with the full path to where y

---