CCX数据库集群管理MCP服务器

@severalnines/ccx-mcp

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

Installation

The server is published on npm as @severalnines/ccx-mcp. Node.js 18 or newer is required. Pick one of:

With a global install, point your MCP client at "command": "ccx-mcp" with no args instead of the npx form shown in the examples.

Quick Start

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>

The easiest way to get this command is the Connect an AI assistant (MCP) card in the CCX UI (shown when your CCX operator has enabled it): it creates a credential and gives you the command with the values filled in. You can also create OAuth2 credentials yourself under Settings > Credentials.

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 datastore, delete database/user/firewall rule/parameter group, apply parameter group, restore backup) are not registered at all by default, so an assistant never sees them. To enable them, add --protect false; each then still requires confirm: true:

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

Rotating the credential

When a credential expires or is revoked, ccx-mcp stops with CCX credential expired, revoked or invalid. Generate a new one at <endpoint>/settings/credentials. Generate a new credential (the Connect an AI assistant (MCP) card gives you both commands below), then replace the registration, since claude mcp add refuses a name that is already registered:

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

If you registered the server without -s user, drop it from both commands.

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 Settings > Credentials 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 Settings > Credentials.

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

Protection mode is on by default. While it is on, the destructive tools are not registered: they do not appear in the tool list, so an AI assistant cannot attempt them at all. The affected tools are:

• ccx_delete_datastore
• ccx_delete_database
• ccx_delete_db_user
• ccx_delete_firewall_rule
• ccx_delete_parameter_group
• ccx_apply_parameter_group
• ccx_restore_backup

To make them available, set CCX_PROTECT=false (or --protect false) and restart the server. Every one of these tools then still requires confirm: true in the call; without it the tool refuses and makes no request.

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

The setting is read once at startup and never changes while the server runs.

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