@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

Related MCP server: NDB MCP Server

Claude Code

Register the server in one command — no manual config file editing required:

claude mcp add ccx -- npx -y @severalnines/ccx-mcp@latest \
  --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.

Then restart Claude Code (or run /mcp and reconnect) and you're ready to go.

Password auth instead of OAuth2

Use --username and --password in place of --client-id / --client-secret:

claude mcp add ccx -- npx -y @severalnines/ccx-mcp@latest \
  --endpoint https://app.myccx.io \
  --username your-email@example.com \
  --password your-password

Allow destructive operations

Destructive tools (delete cluster, delete user, restore backup, etc.) are blocked by default. To allow them, add --protect false:

claude mcp add ccx -- npx -y @severalnines/ccx-mcp@latest \
  --endpoint https://app.myccx.io \
  --client-id <id> --client-secret <secret> \
  --protect false

Managing the server

claude mcp list           # show registered servers
claude mcp remove ccx     # remove the server

All available flags

CLI flags override environment variables when both are set.

Tips

• Pin @latest in the npx invocation (as shown above). Without a version pin, npx may serve a stale cached build instead of fetching the newest from npm.

• If you have an old node_modules/@severalnines/ccx-mcp from a previous install in your project, delete it — npx will resolve to it before checking the registry and run the wrong version.

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"
      }
    }
  }
}

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": "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

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": "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

Cloud & Plans

Database Management

Database Users

Firewall / Trusted Sources

Backups & Recovery

Parameter Groups

Monitoring & Performance

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