@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 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": "your-email@example.com",
        "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": "your-email@example.com",
        "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?"

Authentication

Password Auth

Set CCX_USERNAME and CCX_PASSWORD:

{
  "env": {
    "CCX_BASE_URL": "https://app.myccx.io",
    "CCX_USERNAME": "your-email@example.com",
    "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

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

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

Severalnines CCX MCP Server