Skip to content

Configuration

Jump to bottom
Temp edited this page Mar 1, 2026 · 8 revisions

Configuration

This page covers MCP client configuration, environment variables, and database connection scenarios.

MCP Client Configuration

Cursor IDE

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "node",
      "args": [
        "C:/path/to/mysql-mcp/dist/cli.js",
        "--transport",
        "stdio",
        "--mysql",
        "mysql://user:password@localhost:3306/database",
        "--tool-filter",
        "starter"
      ]
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "node",
      "args": [
        "/path/to/mysql-mcp/dist/cli.js",
        "--transport",
        "stdio",
        "--mysql",
        "mysql://user:password@localhost:3306/database"
      ]
    }
  }
}

Docker Configuration

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "writenotenow/mysql-mcp:latest",
        "--transport",
        "stdio",
        "--mysql",
        "mysql://user:password@host.docker.internal:3306/database"
      ]
    }
  }
}

Note: Use host.docker.internal to connect to MySQL running on your host machine from Docker.

HTTP/SSE Transport (Advanced)

For remote deployments, you can run mysql-mcp as an HTTP server instead of using stdio:

# Local installation
node dist/cli.js --transport http --port 3000 --server-host 0.0.0.0 --mysql mysql://user:password@localhost:3306/database

# Docker with port mapping
docker run -p 3000:3000 writenotenow/mysql-mcp \
  --transport http \
  --port 3000 \
  --server-host 0.0.0.0 \
  --mysql mysql://user:password@host.docker.internal:3306/database

When to use HTTP mode:

  • Deploying to cloud platforms (AWS, GCP, Azure)
  • Multiple AI clients connecting to one database
  • Enabling OAuth 2.1 authentication
  • Running as a standalone network service

💡 Tip: Most users should use stdio mode for local development. See HTTP-Transport for complete HTTP deployment guide.

Environment Variables

For security, use environment variables instead of connection strings:

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "node",
      "args": ["C:/path/to/mysql-mcp/dist/cli.js", "--transport", "stdio"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_user",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Available Variables

Variable Default Description
MYSQL_HOST - MySQL server hostname
MYSQL_PORT 3306 MySQL server port
MYSQL_USER - MySQL username
MYSQL_PASSWORD - MySQL password
MYSQL_DATABASE - Default database
MYSQL_XPORT 33060 X Protocol port (for mysqlsh_import_json and docstore tools)
MYSQL_POOL_SIZE 10 Max connections in pool
MYSQL_POOL_TIMEOUT 10000 Connection timeout (ms)
MCP_HOST localhost Host to bind HTTP transport to

Performance Tuning Variables

Variable Default Description
METADATA_CACHE_TTL_MS 30000 Cache TTL for schema metadata (ms)
LOG_LEVEL info Log verbosity: debug, info, warning, error
CODEMODE_ISOLATION worker Sandbox mode: worker (separate V8 isolate) or vm (in-process sandbox)

Tip: Lower METADATA_CACHE_TTL_MS for development (e.g., 5000), or increase for production with stable schemas (e.g., 300000 = 5 min).

Database Connection Scenarios

🖥️ Local MySQL (Installed on Your Machine)

{
  "env": {
    "MYSQL_HOST": "localhost",
    "MYSQL_PORT": "3306",
    "MYSQL_USER": "root",
    "MYSQL_PASSWORD": "password",
    "MYSQL_DATABASE": "mydb"
  }
}

🐳 Docker MySQL (Container)

Option 1: Port Mapping (Recommended)

If MySQL container uses -p 3306:3306:

{
  "env": {
    "MYSQL_HOST": "localhost",
    "MYSQL_PORT": "3306"
  }
}

Option 2: Container IP

# Find container IP
docker inspect mysql-container | grep IPAddress
{
  "env": {
    "MYSQL_HOST": "172.17.0.2",
    "MYSQL_PORT": "3306"
  }
}

☁️ Remote MySQL (Cloud/RDS)

{
  "args": [
    "--mysql",
    "mysql://admin:password@your-db.us-east-1.rds.amazonaws.com:3306/production"
  ]
}

Common cloud hostnames:

Provider Example Hostname
AWS RDS your-instance.xxxx.us-east-1.rds.amazonaws.com
Google Cloud SQL project:region:instance (via Cloud SQL Proxy)
Azure MySQL your-server.mysql.database.azure.com
PlanetScale aws.connect.psdb.cloud (SSL required)
DigitalOcean your-cluster-do-user-xxx.db.ondigitalocean.com

Tip: Remote connections may require SSL. Check your provider's documentation.

Connection Pooling

MySQL benefits from connection pooling. Configure via environment variables:

{
  "env": {
    "MYSQL_HOST": "localhost",
    "MYSQL_PORT": "3306",
    "MYSQL_USER": "app_user",
    "MYSQL_PASSWORD": "secure_password",
    "MYSQL_DATABASE": "production",
    "MYSQL_POOL_SIZE": "20",
    "MYSQL_POOL_TIMEOUT": "30000"
  }
}

Ecosystem Configuration (Router, ProxySQL, Shell)

For InnoDB Cluster deployments with MySQL Router, ProxySQL, and MySQL Shell:

{
  "env": {
    "MYSQL_HOST": "localhost",
    "MYSQL_PORT": "3307",
    "MYSQL_USER": "cluster_admin",
    "MYSQL_PASSWORD": "cluster_password",
    "MYSQL_DATABASE": "mysql",
    "MYSQL_XPORT": "6448",
    "MYSQL_ROUTER_URL": "https://localhost:8443",
    "MYSQL_ROUTER_USER": "rest_api",
    "MYSQL_ROUTER_PASSWORD": "router_password",
    "MYSQL_ROUTER_INSECURE": "true",
    "PROXYSQL_HOST": "localhost",
    "PROXYSQL_PORT": "6032",
    "PROXYSQL_USER": "radmin",
    "PROXYSQL_PASSWORD": "radmin",
    "MYSQLSH_PATH": "/usr/local/bin/mysqlsh"
  }
}

Important: Router REST API requires the InnoDB Cluster to be running for authentication (uses metadata_cache backend). See MySQL-Router for troubleshooting.

See Also

mysql-mcp • v2.2.0 • MIT License

mysql-mcp Wiki

Getting Started

Tools

Advanced Topics

Links

Clone this wiki locally