Skip to main content
The MySQL MCP Server uses JSON configuration files for database connections and optionally uses OCI config for cloud features.

​
Database Connection Configuration

​
Configuration File Location

The server searches for configuration files in this order:
  1. Path specified by MYSQL_MCP_CONFIG environment variable (absolute or relative to module directory)
  2. local_config.json in the module directory (default)
  3. config.json in the module directory
  4. config.json in the current working directory

​
Basic Configuration Format

The configuration file uses JSON with the following structure: 
{
  "server_infos": {
    "<connection_id>": {
      "host": "<hostname or IP>",
      "user": "<username>",
      "password": "<password>",
      "database": "<default_schema>",
      "port": 3306
    }
  }
}

​
Required Fields

  • host: Hostname or IP address of the MySQL server
  • user: Database username
  • password: Database password
  • database: Default schema/database name
  • port: MySQL port (typically 3306)

​
Example: Simple Local Connection

{
  "server_infos": {
    "local_server": {
      "host": "localhost",
      "user": "root",
      "password": "",
      "database": "mysql_mcp",
      "port": 3306
    }
  }
}

​
Example: Multiple Connections

{
  "server_infos": {
    "dev_db": {
      "host": "dev-mysql.example.com",
      "user": "dev_user",
      "password": "dev_password",
      "database": "app_dev",
      "port": 3306
    },
    "prod_db": {
      "host": "prod-mysql.example.com",
      "user": "prod_user",
      "password": "prod_password",
      "database": "app_prod",
      "port": 3306
    }
  }
}

​
SSH Bastion Configuration

For secure connections through an SSH bastion host, add a bastion section: 
{
  "server_infos": {
    "remote_via_bastion": {
      "host": "127.0.0.1",
      "user": "dbuser",
      "password": "secret",
      "database": "appdb",
      "port": 3306
    }
  },
  "bastion": {
    "bastion_host": "bastion.example.com",
    "bastion_username": "ubuntu",
    "private_key_path": "/home/user/.ssh/id_rsa",
    "db_host": "mysql.internal",
    "db_port": 3306,
    "bastion_port": 22,
    "local_bind_host": "127.0.0.1",
    "local_bind_port": 3306
  }
}

​
Bastion Fields

Required:
  • bastion_host: SSH bastion hostname
  • bastion_username: SSH username
  • private_key_path: Path to SSH private key
  • db_host: Internal database hostname (accessible from bastion)
Optional (with defaults):
  • db_port: Database port (default: 3306)
  • bastion_port: SSH port (default: 22)
  • local_bind_host: Local interface to bind (default: “127.0.0.1”)
  • local_bind_port: Local port for tunnel (default: 3306)

​
OCI Configuration

For OCI Object Storage features and MySQL HeatWave integration, configure OCI credentials.

​
Default Location

The server looks for OCI config at ~/.oci/config. See the OCI SDK documentation for setup instructions.

​
Example OCI Config File

[DEFAULT]
user=ocid1.user.oc1...
fingerprint=aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99
tenancy=ocid1.tenancy.oc1...
region=us-phoenix-1
key_file=/home/user/.oci/oci_api_key.pem

​
Environment Variables

The server supports these environment variables:
  • PROFILE_NAME: OCI configuration profile name (default: “DEFAULT”)
  • TENANCY_ID_OVERRIDE: Override the tenancy ID from the config file

​
When is OCI Config Required?

The OCI config file is only required for:
  • Listing OCI compartments
  • Accessing OCI Object Storage
  • Loading files from Object Storage into vector stores (HeatWave)
MySQL AI connections work without OCI config for all database operations. Cloud-dependent features will fail gracefully with clear error messages if OCI config is missing.

​
MCP Client Configuration

​
Claude Desktop (Windows)

{
  "mcpServers": {
    "mysqltools": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\ABSOLUTE\\PATH\\TO\\mysql-mcp-server",
        "run",
        "oracle.mysql_mcp_server"
      ]
    }
  }
}
On Windows, you may need to use oracle.mysql_mcp_server.exe as the command.

​
Claude Desktop (macOS/Linux)

{
  "mcpServers": {
    "mysqltools": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mysql-mcp-server",
        "run",
        "oracle.mysql_mcp_server"
      ]
    }
  }
}

​
With Environment Variables

Override OCI settings using environment variables: 
{
  "mcpServers": {
    "mysqltools": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mysql-mcp-server",
        "run",
        "oracle.mysql_mcp_server"
      ],
      "env": {
        "MYSQL_MCP_CONFIG": "/path/to/custom_config.json",
        "TENANCY_ID_OVERRIDE": "ocid1.tenancy.oc1...",
        "PROFILE_NAME": "PRODUCTION"
      }
    }
  }
}

​
Configuration Validation

The server validates configuration at startup:
  • Schema Validation: Ensures all required fields are present
  • Default Application: Applies defaults for optional bastion settings
  • Clear Error Messages: Raises exceptions for invalid or incomplete configurations

​
Common Configuration Errors

Ensure each connection in server_infos has all required fields: host, user, password, database, and port.
// ❌ Invalid - missing 'port'
{
  "server_infos": {
    "mydb": {
      "host": "localhost",
      "user": "root",
      "password": "",
      "database": "test"
    }
  }
}

// ✅ Valid
{
  "server_infos": {
    "mydb": {
      "host": "localhost",
      "user": "root",
      "password": "",
      "database": "test",
      "port": 3306
    }
  }
}
If a bastion block is present, only allowed keys are permitted. Extra keys will cause validation errors.Allowed keys: bastion_host, bastion_username, private_key_path, db_host, db_port, bastion_port, local_bind_host, local_bind_port
If MYSQL_MCP_CONFIG is set but the file doesn’t exist, or if none of the default locations contain a config file, the server will fail to start.Check:
  • MYSQL_MCP_CONFIG environment variable points to an existing file
  • local_config.json exists in the module directory
  • File permissions allow reading

​
Security Best Practices

Never commit configuration files containing passwords to version control.
  • Use .gitignore to exclude local_config.json and other credential files
  • Use environment variables for sensitive values in production
  • Restrict file permissions: chmod 600 config.json
  • Consider using SSH bastion hosts for remote database access
  • Rotate passwords regularly

​
Next Steps

API Tools

Explore available database and ML tools

Vector Stores

Set up vector stores for RAG applications

Build docs developers (and LLMs) love

Get started for freeTalk to us