Troubleshooting

Connection Issues

Verify MySQL is running and accessible
Check credentials and user permissions
Verify SSL/TLS config if enabled
Test with a MySQL client directly

Path resolution error ("Could not connect to MCP server"):

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

Find paths:

echo "$(which node)/../"                     # PATH value
echo "$(which node)/../../lib/node_modules"  # NODE_PATH value

Performance Issues

Increase MYSQL_POOL_SIZE
Raise MYSQL_QUERY_TIMEOUT
Enable MYSQL_CACHE_TTL
Reduce MYSQL_MAX_QUERY_COMPLEXITY

Security Restrictions

Check MYSQL_RATE_LIMIT
Verify write operation flags (ALLOW_INSERT_OPERATION, etc.)
Confirm MySQL user has required privileges

Claude Code / Claude Desktop

"Server disconnected" — check logs at:

~/Library/Logs/Claude/mcp-server-mcp_server_mysql.log

Use absolute paths for both Node binary and server script
Ensure .env is loaded or env vars are set explicitly in config
Test the server directly: node dist/index.js

Enable write ops if needed:

"env": {
  "ALLOW_INSERT_OPERATION": "true",
  "ALLOW_UPDATE_OPERATION": "true",
  "ALLOW_DELETE_OPERATION": "true"
}

Direct execution config:

{
  "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 (MySQL 8.0+)

Ensure caching_sha2_password is supported, or create a user with legacy auth:

CREATE USER 'user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';

`ERR_MODULE_NOT_FOUND: Cannot find package 'dotenv'`

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

Thanks to @lizhuangs

FilesExpand file tree

TROUBLESHOOTING.md

Latest commit

History