@severalnines/ccx-mcp

MCP (Model Context Protocol) server for managing CCX database clusters through AI assistants like Claude Code, Claude Desktop, Cursor, and Windsurf.

Quick Start

Install via Claude Code

After installing the package (npm install -g @severalnines/ccx-mcp or as a project dependency), register it with Claude Code in one command:

claude mcp add ccx -- ccx-mcp \
  --endpoint https://app.myccx.io \
  --client-id <your-client-id> \
  --client-secret <your-client-secret>

Create OAuth2 credentials in the CCX UI under Account > Security.

To disable protection mode (allow destructive operations) add --protect false.

CLI flags override environment variables. Available flags:

| Flag | Maps to | |------|---------| | --endpoint <url> | CCX_BASE_URL | | --client-id <id> | CCX_CLIENT_ID | | --client-secret <secret> | CCX_CLIENT_SECRET | | --username <email> | CCX_USERNAME | | --password <password> | CCX_PASSWORD | | --protect <true\|false> | CCX_PROTECT | | -h, --help | Show usage |

For password auth, use --username and --password in place of --client-id / --client-secret.

Install from npm

Add this to your MCP client configuration:

{
  "mcpServers": {
    "ccx": {
      "command": "npx",
      "args": ["-y", "@severalnines/ccx-mcp"],
      "env": {
        "CCX_BASE_URL": "https://app.myccx.io",
        "CCX_USERNAME": "[email protected]",
        "CCX_PASSWORD": "your-password"
      }
    }
  }
}

Alternative: install as a project dependency

If npx causes issues (e.g. spawning errors or version caching problems), you can install the package as a dependency and reference it directly:

npm install @severalnines/ccx-mcp

Then use this configuration:

{
  "mcpServers": {
    "ccx": {
      "command": "node",
      "args": ["node_modules/@severalnines/ccx-mcp/build/index.js"],
      "env": {
        "CCX_BASE_URL": "https://app.myccx.io",
        "CCX_USERNAME": "[email protected]",
        "CCX_PASSWORD": "your-password"
      }
    }
  }
}

Install from source

git clone https://github.com/severalnines/ccx-mcp.git
cd ccx-mcp
npm install
npm run build

Then point your MCP client to the built server (replace the path with where you cloned the repo):

{
  "mcpServers": {
    "ccx": {
      "command": "node",
      "args": ["/home/user/ccx-mcp/build/index.js"],
      "env": {
        "CCX_BASE_URL": "https://app.myccx.io",
        "CCX_USERNAME": "[email protected]",
        "CCX_PASSWORD": "your-password"
      }
    }
  }
}

Or use OAUTH2 credentials (create them under Accounts -> Security in the CCX UI):

    "CCX_CLIENT_ID": "your-client-id",
    "CCX_CLIENT_SECRET": "your-client-secret"

Where to put the configuration

| MCP Client | Config file | |------------|-------------| | Claude Code | .mcp.json in your project root, or ~/.claude/.mcp.json for global | | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) | | Cursor | .cursor/mcp.json in your project root | | Windsurf | ~/.codeium/windsurf/mcp_config.json |

CCX_BASE_URL

This is the URL of your CCX deployment. If you're using the hosted CCX service, it's typically https://app.myccx.io. If you're running a self-hosted CCX instance, use its URL instead.

Using OAuth2 instead of password

Replace CCX_USERNAME and CCX_PASSWORD with CCX_CLIENT_ID and CCX_CLIENT_SECRET:

{
  "mcpServers": {
    "ccx": {
      "command": "npx",
      "args": ["-y", "@severalnines/ccx-mcp"],
      "env": {
        "CCX_BASE_URL": "https://app.myccx.io",
        "CCX_CLIENT_ID": "your-client-id",
        "CCX_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

You can create OAuth2 credentials in the CCX UI under Account > Security.

Then ask your AI assistant things like:

• "List my datastores"
• "Create a PostgreSQL cluster on AWS in eu-west-1"
• "Get the connection string for my production database"
• "Add 10.0.0.0/24 as a trusted source on my cluster"
• "Create a new database user called appuser"
• "Scale my cluster to a medium instance"
• "Show me the slowest queries on my database"
• "List backups for my production cluster"
• "What's the CPU usage on my database?"
• "List the default parameters for PostgreSQL 16"
• "Create a parameter group for MySQL 8.4 with max_connections set to 500"

Authentication

Password Auth

Set CCX_USERNAME and CCX_PASSWORD:

{
  "env": {
    "CCX_BASE_URL": "https://app.myccx.io",
    "CCX_USERNAME": "[email protected]",
    "CCX_PASSWORD": "your-password"
  }
}

OAuth2 (Client Credentials)

For programmatic or CI/CD use, set CCX_CLIENT_ID and CCX_CLIENT_SECRET instead:

{
  "env": {
    "CCX_BASE_URL": "https://app.myccx.io",
    "CCX_CLIENT_ID": "your-client-id",
    "CCX_CLIENT_SECRET": "your-client-secret"
  }
}

Available Tools

Datastore Management

| Tool | Description | |------|-------------| | ccx_list_datastores | List all database clusters with status, vendor, and cloud provider | | ccx_get_datastore | Get detailed cluster info including credentials and job progress | | ccx_create_datastore | Create a new cluster (only vendor, cloud provider, and region required) | | ccx_delete_datastore | Delete a cluster (requires explicit confirmation) | | ccx_get_nodes | Get cluster nodes with roles, status, and IP addresses | | ccx_get_connection_string | Connection strings in URI, CLI, JDBC, and env formats | | ccx_scale_datastore | Scale instance size (CPU/RAM) or expand storage volume | | ccx_add_node | Add a new replica node to a cluster |

Cloud & Plans

| Tool | Description | |------|-------------| | ccx_list_clouds | List available cloud providers and regions | | ccx_list_plans | List instance sizes, volume types, and sizes per cloud |

Database Management

| Tool | Description | |------|-------------| | ccx_list_databases | List databases on a datastore | | ccx_create_database | Create a new database | | ccx_delete_database | Delete a database |

Database Users

| Tool | Description | |------|-------------| | ccx_list_db_users | List database users with grants and auth plugins | | ccx_create_db_user | Create a user with configurable privileges, host, and admin flag | | ccx_delete_db_user | Delete a database user |

Firewall / Trusted Sources

| Tool | Description | |------|-------------| | ccx_list_firewall_rules | List trusted source CIDRs and allowed ports | | ccx_create_firewall_rule | Allow a CIDR to connect to the database | | ccx_delete_firewall_rule | Remove a trusted source CIDR |

Backups & Recovery

| Tool | Description | |------|-------------| | ccx_list_backups | List available backups with status, type, and timestamps | | ccx_restore_backup | Restore from a backup with optional point-in-time recovery |

Parameter Groups

| Tool | Description | |------|-------------| | ccx_list_parameter_groups | List parameter groups with optional filtering by vendor, version, or name | | ccx_get_parameter_group | Get a parameter group with its full list of parameters | | ccx_create_parameter_group | Create a new parameter group with custom database configuration | | ccx_update_parameter_group | Update parameters, optionally syncing changes to all associated datastores | | ccx_delete_parameter_group | Delete a parameter group (requires explicit confirmation) | | ccx_apply_parameter_group | Apply a parameter group to a datastore | | ccx_list_default_parameters | Get default parameters for a vendor and version to see available options |

Monitoring & Performance

| Tool | Description | |------|-------------| | ccx_get_top_queries | Get slowest queries ranked by execution time | | ccx_get_stats | Get performance metrics (CPU, memory, disk, network, SQL, DB stats) |

Protection Mode

Destructive operations are blocked by default to prevent accidental data loss. The following tools are affected:

• ccx_delete_datastore — deletes an entire database cluster
• ccx_delete_db_user — deletes a database user account
• ccx_delete_database — deletes a database
• ccx_delete_firewall_rule — removes a firewall access rule
• ccx_restore_backup — overwrites current data with a backup
• ccx_delete_parameter_group — deletes a parameter group
• ccx_apply_parameter_group — applies configuration changes to a datastore

To allow destructive operations, set CCX_PROTECT=false in your MCP configuration and restart the server:

{
  "env": {
    "CCX_PROTECT": "false"
  }
}

Supported Databases

• PostgreSQL
• MySQL / Percona
• MariaDB
• Redis
• Valkey
• Microsoft SQL Server

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode
npm run test:watch

Requirements

• Node.js 18+
• A CCX account at ccx.severalnines.com

License

Apache-2.0