MCP Server for MySQL - Security-Hardened Fork

🔒 Security-hardened fork of @benborla29/mcp-server-mysql Package: @zilosoft/mcp-server-mysql Original Author: @benborla29 Original Repository: https://github.com/benborla/mcp-server-mysql Fork Maintainer: @ZILosoft License: MIT

MCP Server for MySQL based on NodeJS

Security Fixes in This Fork

🔒 Constant-time Bearer token comparison — prevents timing attacks on the remote MCP secret
🔒 Strict SSL validation — at startup the server requires either a CA certificate (MYSQL_SSL_CA) or explicit opt-out (MYSQL_SSL_SKIP_VERIFY=true); no more silent MITM-vulnerable encryption
🔒 SSL auto-detection — remote hosts automatically get SSL enabled; localhost/sockets skip it
🔒 AST-based schema extraction — replaces regex-only parser; fixes permission bypass via cross-database references like INSERT INTO forbidden_db.users
🔒 Removed mysql_clear_password plaintext auth plugin
🔒 Enforced multi-DB write lockdown — in multi-DB mode, writes are truly disabled unless MULTI_DB_WRITE_MODE=true
🔒 Zod input validation on the mysql_query tool parameter
🔒 Masked SSL file paths in startup logs

Key Features (inherited from upstream)

✅ 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

Read the Setup Guide: See PROJECT_SETUP_GUIDE.md for detailed instructions
Configure SSH Tunnels: Set up automatic SSH tunnels for remote databases
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.

Requirements
Installation
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

Docker

Pre-built Docker images are published to the GitHub Container Registry on every release:

docker pull ghcr.io/zilosoft/mcp-server-mysql:latest
# or a specific version
docker pull ghcr.io/zilosoft/mcp-server-mysql:2.1.0

Run with environment variables:

docker run --rm \
  -e MYSQL_HOST=your-host \
  -e MYSQL_PORT=3306 \
  -e MYSQL_USER=your-user \
  -e MYSQL_PASS=your-password \
  -e MYSQL_DB=your-database \
  ghcr.io/zilosoft/mcp-server-mysql:latest

Available tags: latest, X.Y.Z, X.Y, X — all pointing to the security-hardened @zilosoft build.

Note: This security-hardened fork is published as @zilosoft/mcp-server-mysql. The Smithery and Cursor one-click installs below point to the original upstream @benborla29/mcp-server-mysql package, which does NOT include the security fixes from this fork. To get the hardened build, install @zilosoft/mcp-server-mysql via npm/pnpm as shown in the other sections.

Using Smithery

⚠️ Upstream only — this Smithery install does NOT include the security fixes from this fork. To get the hardened build, install @zilosoft/mcp-server-mysql via npm/pnpm as shown in the sections below.

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

⚠️ Upstream only — this Cursor install does NOT include the security fixes from this fork.

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

Visit https://smithery.ai/server/@benborla29/mcp-server-mysql
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 @zilosoft/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 @zilosoft/mcp-server-mysql

# Using pnpm
pnpm add -g @zilosoft/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 @zilosoft/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 @zilosoft/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 @zilosoft/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 @zilosoft/mcp-server-mysql

Troubleshooting Claude Code Setup

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

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"

Permission Errors: Ensure your MySQL user has appropriate permissions for the operations you've enabled.
Server Not Starting: Check Claude Code logs or run the server directly to debug:
```
# Test the server directly
npx @zilosoft/mcp-server-mysql
```

Using NPM/PNPM

For manual installation:

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

# Using pnpm
pnpm add -g @zilosoft/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:

Clone the repository

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

Install dependencies
```
npm install
# or
pnpm install
```
Build the project
```
npm run build
# or
pnpm run build
```

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 you cloned the repository
Set the MySQL credentials to match your environment

Test the server
```
# Run the server directly to test
node dist/index.js
```
If it connects to MySQL successfully, you're ready to use it with Claude Desktop.

Run in remote mode

To run in remote mode, you'll need to provide environment variables to the npx script.

Create env file in preferred directory
```
# create .env file
touch .env
```
Copy-paste example file from this repository
Set the MySQL credentials to match your environment
Set IS_REMOTE_MCP=true
Set REMOTE_SECRET_KEY to a secure string.
Provide custom PORT if needed. Default is 3000.
Load variables in current session:
```
source .env
```
Run the server
```
npx @zilosoft/mcp-server-mysql
```

Configure your agent to connect to the MCP with the next configuration:

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

Components

Tools

mysql_query
- Execute SQL queries against the connected database
- Input: sql (string): The SQL query to execute
- By default, limited to READ ONLY operations
- Optional write operations (when enabled via configuration):
  - INSERT: Add new data to tables (requires ALLOW_INSERT_OPERATION=true)
  - UPDATE: Modify existing data (requires ALLOW_UPDATE_OPERATION=true)
  - DELETE: Remove data (requires ALLOW_DELETE_OPERATION=true)
- All operations are executed within a transaction with proper commit/rollback handling
- Supports prepared statements for secure parameter handling
- Configurable query timeouts and result pagination
- Built-in query execution statistics

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
- Automatically discovered from database metadata

Security Features

SQL injection prevention through prepared statements
Query whitelisting/blacklisting capabilities
Rate limiting for query execution
Query complexity analysis
Configurable connection encryption
Read-only transaction enforcement

Performance Optimizations

Optimized connection pooling
Query result caching
Large result set streaming
Query execution plan analysis
Configurable query timeouts

Monitoring and Debugging

Comprehensive query logging
Performance metrics collection
Error tracking and reporting
Health check endpoints
Query execution statistics

Configuration

Automatic Configuration with Smithery

If you installed using Smithery, your configuration is already set up. You can view or modify it with:

smithery configure @benborla29/mcp-server-mysql

When reconfiguring, you can update any of the MySQL connection details as well as the write operation settings:

Basic connection settings:
- MySQL Host, Port, User, Password, Database
- SSL/TLS configuration (if your database requires secure connections)
Write operation permissions:
- Allow INSERT Operations: Set to true if you want to allow adding new data
- Allow UPDATE Operations: Set to true if you want to allow updating existing data
- Allow DELETE Operations: Set to true if you want to allow deleting data

For security reasons, all write operations are disabled by default. Only enable these settings if you specifically need Claude to modify your database data.

Advanced Configuration Options

For more control over the MCP server's behavior, you can use these advanced configuration options:

{
  "mcpServers": {
    "mcp_server_mysql": {
      "command": "/path/to/npx/binary/npx",
      "args": [
        "-y",
        "@zilosoft/mcp-server-mysql"
      ],
      "env": {
        // Basic connection settings
        "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",

        // Performance settings
        "MYSQL_POOL_SIZE": "10",
        "MYSQL_QUERY_TIMEOUT": "30000",
        "MYSQL_CACHE_TTL": "60000",

        // Security settings
        "MYSQL_RATE_LIMIT": "100",
        "MYSQL_MAX_QUERY_COMPLEXITY": "1000",
        "MYSQL_SSL": "true",

        // Monitoring settings
        "ENABLE_LOGGING": "true",
        "MYSQL_LOG_LEVEL": "info",
        "MYSQL_METRICS_ENABLED": "true",

        // Write operation flags
        "ALLOW_INSERT_OPERATION": "false",
        "ALLOW_UPDATE_OPERATION": "false",
        "ALLOW_DELETE_OPERATION": "false"
      }
    }
  }
}

Environment Variables

Basic Connection

MYSQL_SOCKET_PATH: Unix socket path for local connections (e.g., "/tmp/mysql.sock")
MYSQL_HOST: MySQL server host (default: "127.0.0.1") - ignored if MYSQL_SOCKET_PATH is set
MYSQL_PORT: MySQL server port (default: "3306") - ignored if MYSQL_SOCKET_PATH is set
MYSQL_USER: MySQL username (default: "root")
MYSQL_PASS: MySQL password
MYSQL_DB: Target database name (leave empty for multi-DB mode)

Alternative: Connection String

For scenarios requiring frequent credential rotation or temporary connections, you can use a MySQL connection string instead of individual environment variables:

MYSQL_CONNECTION_STRING: MySQL CLI-format connection string (e.g., mysql --default-auth=mysql_native_password -A -hHOST -PPORT -uUSER -pPASS database_name)

When MYSQL_CONNECTION_STRING is provided, it takes precedence over individual connection settings. This is particularly useful for:

Rotating credentials that expire frequently
Temporary database connections
Quick testing with different database configurations

Note: For security, this should only be set via environment variables, not stored in version-controlled configuration files. Consider using the prompt input type in Claude Code's MCP configuration for credentials that expire.

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")
MYSQL_QUEUE_LIMIT: Maximum number of queued connection requests (default: "100")
MYSQL_CONNECT_TIMEOUT: Connection timeout in milliseconds (default: "10000")

Security Configuration

SSL / TLS (updated in this fork)

This fork introduces SSL auto-detection with strict verification. The behaviour is:

If MYSQL_SSL is explicitly set ("true" or "false") — the server respects it.
If the connection is a Unix socket — SSL is not used.
If the host is localhost / 127.0.0.1 / ::1 / 0.0.0.0 — SSL is not used.
Otherwise (remote host) — SSL is auto-enabled.

When SSL is active (by any path above), the server refuses to start unless one of these is explicitly set:

MYSQL_SSL_CA=/path/to/ca.pem — enables strict certificate verification (recommended)
MYSQL_SSL_SKIP_VERIFY=true — disables certificate verification (⚠️ MITM-vulnerable, not recommended for production)

This prevents the common footgun where SSL gives encryption without authentication. See the "Startup error: SSL is enabled but no CA…" entry in the Troubleshooting section below for a full resolution guide.

Variable	Description
`MYSQL_SSL`	`"true"` / `"false"` to override auto-detection. Leave unset to let the server decide based on host.
`MYSQL_SSL_CA`	Path to CA certificate (PEM). Enables verified TLS when SSL is active.
`MYSQL_SSL_SKIP_VERIFY`	Set to `"true"` to explicitly disable certificate verification. Required instead of `MYSQL_SSL_CA` if you don't have a CA.
`MYSQL_SSL_REJECT_UNAUTHORIZED`	Legacy alias — `"false"` is equivalent to `MYSQL_SSL_SKIP_VERIFY=true`. Prefer the new variable in new configs.
`MYSQL_SSL_CERT`	Client certificate (PEM) for mTLS. Requires `MYSQL_SSL_KEY`.
`MYSQL_SSL_KEY`	Client private key (PEM) for mTLS. Must match `MYSQL_SSL_CERT`.

Connection strings (MYSQL_CONNECTION_STRING) also understand --ssl, --ssl-mode=REQUIRED|DISABLED|VERIFY_CA|…, and --ssl-ca=/path.

Write operations and permissions

Variable	Default	Description
`ALLOW_INSERT_OPERATION`	`"false"`	Allow `INSERT` queries
`ALLOW_UPDATE_OPERATION`	`"false"`	Allow `UPDATE` queries
`ALLOW_DELETE_OPERATION`	`"false"`	Allow `DELETE` queries
`ALLOW_DDL_OPERATION`	`"false"`	Allow DDL (`CREATE`/`ALTER`/`DROP`/`TRUNCATE`)
`SCHEMA_INSERT_PERMISSIONS`	(empty)	Per-schema INSERT overrides, e.g. `dev:true,prod:false`
`SCHEMA_UPDATE_PERMISSIONS`	(empty)	Per-schema UPDATE overrides
`SCHEMA_DELETE_PERMISSIONS`	(empty)	Per-schema DELETE overrides
`SCHEMA_DDL_PERMISSIONS`	(empty)	Per-schema DDL overrides
`MULTI_DB_WRITE_MODE`	`"false"`	Hard safety lock: in multi-DB mode (no `MYSQL_DB` set), writes are force-disabled regardless of the `ALLOW_*` flags unless this is `"true"`. This is now actually enforced (not just logged) as of this fork.
`MYSQL_DISABLE_READ_ONLY_TRANSACTIONS`	`"false"`	Disable `SET SESSION TRANSACTION READ ONLY` for SELECT queries. ⚠️ Only set if you need DDL support and trust the LLM.
`MYSQL_RATE_LIMIT`	`"100"`	(reserved — not currently enforced in code)
`MYSQL_MAX_QUERY_COMPLEXITY`	`"1000"`	(reserved — not currently enforced in code)

Timezone and Date Configuration

MYSQL_TIMEZONE: Set the timezone for date/time values. Accepts formats like +08:00 (UTC+8), -05:00 (UTC-5), Z (UTC), or local (system timezone). Useful for ensuring consistent date/time handling across different server locations.
MYSQL_DATE_STRINGS: When set to "true", returns date/datetime values as strings instead of JavaScript Date objects. This preserves the exact database values without any timezone conversion, which is particularly useful for:
- Applications that need precise control over date formatting
- Cross-timezone database operations
- Avoiding JavaScript Date timezone quirks

Monitoring Configuration

MYSQL_ENABLE_LOGGING: Enable query logging (default: "false")
MYSQL_LOG_LEVEL: Logging level (default: "info")
MYSQL_METRICS_ENABLED: Enable performance metrics (default: "false")

Remote MCP Configuration

IS_REMOTE_MCP: Enable remote MCP mode (default: "false")
REMOTE_SECRET_KEY: Secret key for remote MCP authentication (default: ""). If not provided, remote MCP mode will be disabled.
PORT: Port number for the remote MCP server (default: 3000)

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. For full details, see README-MULTI-DB.md.

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;

Schema-Specific Permissions

For fine-grained control over database operations, MCP-Server-MySQL now supports schema-specific permissions. This allows different databases to have different levels of access (read-only, read-write, etc.).

Configuration Example

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

For complete details and security recommendations, see README-MULTI-DB.md.

Testing

Database Setup

Before running tests, you need to set up the test database and seed it with test data:

Create Test Database and User

-- Connect as root and create test database
CREATE DATABASE IF NOT EXISTS mcp_test;

-- Create test user with appropriate permissions
CREATE USER IF NOT EXISTS 'mcp_test'@'localhost' IDENTIFIED BY 'mcp_test_password';
GRANT ALL PRIVILEGES ON mcp_test.* TO 'mcp_test'@'localhost';
FLUSH PRIVILEGES;

Run Database Setup Script
```
# Run the database setup script
pnpm run setup:test:db
```
This will create the necessary tables and seed data. The script is located in scripts/setup-test-db.ts

Configure Test Environment Create a .env.test file in the project root (if not existing):

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=mcp_test
MYSQL_PASS=mcp_test_password
MYSQL_DB=mcp_test

Update package.json Scripts Add these scripts to your package.json:

{
  "scripts": {
    "setup:test:db": "ts-node scripts/setup-test-db.ts",
    "pretest": "pnpm run setup:test:db",
    "test": "vitest run",
    "test:watch": "vitest",
    "test:coverage": "vitest run --coverage"
  }
}

Running Tests

The project includes a comprehensive test suite to ensure functionality and reliability:

# First-time setup
pnpm run setup:test:db

# Run all tests
pnpm test

Running evals

The evals package loads an mcp client that then runs the index.ts file, so there is no need to rebuild between tests. You can load environment variables by prefixing the npx command. Full documentation can be found at MCP Evals.

OPENAI_API_KEY=your-key  npx mcp-eval evals.ts index.ts

Troubleshooting

Common Issues

Startup error: SSL is enabled but no CA…

If the server refuses to start with:
```
SSL is enabled but neither a CA certificate nor a skip-verify flag is set.
  - Provide MYSQL_SSL_CA=/path/to/ca.pem for secure verified connections, OR
  - Set MYSQL_SSL_SKIP_VERIFY=true to explicitly disable certificate verification
    (NOT recommended for production — vulnerable to MITM attacks).
```
…it's because your MYSQL_HOST is not local, so SSL was auto-enabled, but you haven't told the server how to verify the server's certificate. You have three options, in order of preference:

Option A — provide a CA certificate (recommended)
```
"env": {
  "MYSQL_HOST": "db.internal.example",
  "MYSQL_SSL_CA": "/etc/ssl/mysql/ca.pem"
}
```
Option B — skip verification (encrypted but MITM-vulnerable)
```
"env": {
  "MYSQL_HOST": "db.internal.example",
  "MYSQL_SSL_SKIP_VERIFY": "true"
}
```
Option C — disable SSL entirely (only for trusted networks like SSH tunnels)
```
"env": {
  "MYSQL_HOST": "db.internal.example",
  "MYSQL_SSL": "false"
}
```
If you're using an SSH tunnel or 1Password op wrapper, the actual host the server sees after substitution might be 127.0.0.1 (tunnel endpoint) — in that case SSL won't auto-enable and you don't need any of these flags.
Connection Issues
- Verify MySQL server is running and accessible
- Check credentials and permissions
- Ensure SSL/TLS configuration is correct if enabled
- Try connecting with a MySQL client to confirm access
Performance Issues
- Adjust connection pool size
- Configure query timeout values
- Enable query caching if needed
- Check query complexity settings
- Monitor server resource usage
Security Restrictions
- Review rate limiting configuration
- Check query whitelist/blacklist settings
- Verify SSL/TLS settings
- Ensure the user has appropriate MySQL permissions
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"
  }
}
```
Where can I find my node bin path Run the following command to get it:

For PATH
```
echo "$(which node)/../"
```
For NODE_PATH
```
echo "$(which node)/../../lib/node_modules"
```
Claude Desktop Specific Issues
- If you see "Server disconnected" logs in Claude Desktop, check the logs at ~/Library/Logs/Claude/mcp-server-mcp_server_mysql.log
- Ensure you're using the absolute path to both the Node binary and the server script
- Check if your .env file is being properly loaded; use explicit environment variables in the configuration
- Try running the server directly from the command line to see if there are connection issues
- If you need write operations (INSERT, UPDATE, DELETE), set the appropriate flags to "true" in your configuration:
```
"env": {
  "ALLOW_INSERT_OPERATION": "true",  // Enable INSERT operations
  "ALLOW_UPDATE_OPERATION": "true",  // Enable UPDATE operations
  "ALLOW_DELETE_OPERATION": "true"   // Enable DELETE operations
}
```
- Ensure your MySQL user has the appropriate permissions for the operations you're enabling
- For direct execution configuration, use:
```
{
  "mcpServers": {
    "mcp_server_mysql": {
      "command": "/full/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"
      }
    }
  }
}
```
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
- Try creating a user with legacy authentication if needed:
```
CREATE USER 'user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';
```
  @lizhuangs
I am encountering Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'dotenv' imported from error try this workaround:
```
npx -y -p @zilosoft/mcp-server-mysql -p dotenv mcp-server-mysql
```
Thanks to @lizhuangs

Contributing

Contributions are welcome! Please feel free to submit a Pull Request to https://github.com/benborla/mcp-server-mysql

Many Thanks to the following Contributors

Development Setup

Clone the repository
Install dependencies: pnpm install
Build the project: pnpm run build
Run tests: pnpm test

Project Roadmap

We're actively working on enhancing this MCP server. Check our CHANGELOG.md for details on planned features, including:

Enhanced query capabilities with prepared statements
Advanced security features
Performance optimizations
Comprehensive monitoring
Expanded schema information

If you'd like to contribute to any of these areas, please check the issues on GitHub or open a new one to discuss your ideas.

Submitting Changes

Fork the repository
Create a feature branch: git checkout -b feature/your-feature-name
Commit your changes: git commit -am 'Add some feature'
Push to the branch: git push origin feature/your-feature-name
Submit a pull request

License

This MCP server is licensed under the MIT License. See the LICENSE file for details.

@zilosoft/mcp-server-mysql

Quick Install