@terynas/cpanel-mcp

MCP server that gives AI agents (Cursor, Claude Code, Claude Desktop, VS Code, …) access to cPanel WHM API and UAPI over HTTPS. It runs locally on your machine and manages remote cPanel/WHM servers.

Node.js ≥ 20 — distributed on npm.

npm install -g @terynas/cpanel-mcp
cpanel-mcp --list-tools

Prerequisites

| Requirement | Version | |-------------|---------| | Node.js | ≥ 20 | | npm | any recent version |

For API access you need an API token from WHM or cPanel (not a password).

1. Install

npm install -g @terynas/cpanel-mcp

Verify:

cpanel-mcp --help
cpanel-mcp --list-tools

If cpanel-mcp is not on your PATH, add the npm global bin directory:

npm bin -g    # e.g. ~/.npm-global/bin or /usr/local/bin

2. API tokens

Tokens are never written in YAML — only the env variable name (token_env) goes in the config.

WHM token (root / reseller)

1. WHM → Development → Manage API Tokens
2. Create a token and copy the value
3. In your shell:

export WHM_TOKEN_PROD='your-whm-token'

UAPI token (cPanel user)

1. cPanel → Security → Manage API Tokens
2. Create a token
3. In your shell:

export SHOP_UAPI_TOKEN='token-for-shopuser'
export CLIENT_UAPI_TOKEN='token-for-clientacct'

Each profile can use a different env variable — pick names that match token_env in your YAML.

3. Configuration file

MCP looks for config in this order:

1. --config /path/to/config.yaml
2. env CPANEL_MCP_CONFIG
3. ~/.cpanel-mcp/config.yaml ← standard location
4. /etc/cpanel-mcp/config.yaml

Minimal example — WHM

mkdir -p ~/.cpanel-mcp
cat > ~/.cpanel-mcp/config.yaml <<'YAML'
default_server: prod-whm

servers:
  prod-whm:
    type: whm
    host: whm.example.com
    port: 2087
    auth:
      method: token
      username: root
      token_env: WHM_TOKEN_PROD
    spec_version: auto
    verify_tls: true
    timeout_seconds: 60
YAML

Minimal example — UAPI (single cPanel account)

default_server: client-uapi

servers:
  client-uapi:
    type: uapi
    host: cpanel-client.example.com
    port: 2083
    auth:
      method: token
      username: clientacct
      token_env: CLIENT_UAPI_TOKEN
    spec_version: auto
    verify_tls: true
    timeout_seconds: 60

Config fields

| Field | Description | |-------|-------------| | type | whm (port 2087) or uapi (port 2083) | | host | Hostname/IP only, no https:// | | username | WHM/cPanel user the token belongs to | | token_env | Name of the env variable holding the token | | spec_version | auto — server picks the OpenAPI spec version | | verify_tls | true in production | | allowed_operations / denied_operations | Optional restriction of WHM/UAPI calls |

Use the minimal WHM and UAPI examples in section 3 as templates for ~/.cpanel-mcp/config.yaml.

4. Connect your AI client

cpanel-mcp uses stdio MCP (default). Every supported client registers the same local process:

| Setting | Typical value | |---------|----------------| | Command | cpanel-mcp (or full path from which cpanel-mcp) | | Args | --config and path to ~/.cpanel-mcp/config.yaml | | Env | All token_env variables your YAML profiles reference |

Most clients do not inherit tokens from your shell. Put them in the client’s MCP config (env block) or in a wrapper script that exports variables before starting cpanel-mcp.

After changing config, tokens, or cpanel-mcp-ctx use …, restart or reload the MCP server in that client.

What the agent gets

8 MCP tools (dispatcher model):

• list_servers, get_server_info
• list_modules, list_endpoints, describe_endpoint
• call_whm, call_uapi
• refresh_specs (disabled unless you set CPANEL_MCP_ALLOW_REFRESH=1)

Example chat prompts:

“What domains do you see on this account?”

“List all cPanel accounts on the WHM server.”