Skip to main content
Glama

ItchWHMMCP

A local Model Context Protocol (MCP) server for managing WHM and cPanel servers through MCP-compatible AI clients. It supports multiple WHM accounts from a private local configuration file and exposes server health, account, DNS, email, database, SSL, bandwidth, disk, cron, and service-management tools.

Security warning: this server can perform root-level WHM actions. Run it only on machines and with AI clients you trust, scope WHM API tokens as tightly as your workflow allows, and confirm destructive actions before execution.


Compatible Clients

Client

Config File

Notes

Claude Desktop

claude_desktop_config.json

Full support

Cursor

.cursor/mcp.json

Full support

Windsurf

~/.codeium/windsurf/mcp_config.json

Full support

VS Code + Copilot

.vscode/mcp.json

Requires MCP support/extension

Cline

MCP settings UI

Full support

Continue

config.json

Full support

Any stdio MCP host

Client-specific

Standard stdio transport


Related MCP server: cPanel MCP Server

Features

Category

Capabilities

Server Health

Load averages, memory, CPU, uptime

Account Management

List, create, suspend, unsuspend, terminate cPanel accounts

DNS

List zones and query records per domain

MySQL

List databases across the server

Bandwidth

Usage per account or server-wide

SSL

List installed certificates

Services

Check and restart Apache, MySQL, Exim, FTP

Diagnostics

Load averages, optional SSH process snapshots, memory, and disk checks

Security

cPHulk brute-force reports/unblock actions, optional CSF firewall checks and IP allow/deny/remove

Email

List and create mailboxes, list forwarders

Disk

Server-wide and per-account disk usage

Cron Jobs

List scheduled tasks per cPanel account

Subdomains

List subdomains and addon domains

The server currently exposes 30 tools across WHM root-level and cPanel account-level operations.


Requirements

  • Python 3.11+

  • An MCP-compatible AI client

  • WHM server access with an API token


Installation

1. Clone the repository

git clone https://github.com/manofsadness/ItchWHMMCP.git
cd ItchWHMMCP

2. Create a virtual environment

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate

Windows:

python -m venv .venv
.venv\Scripts\Activate.ps1

3. Install dependencies

pip install mcp httpx asyncssh

Configuration

Step 1 - Generate WHM API Tokens

For each server you want to connect:

  1. Log in to WHM.

  2. Open Development > Manage API Tokens.

  3. Generate a token for this MCP server.

  4. Copy the token immediately; WHM shows it only once.

  5. Repeat for each server you want to manage.

Step 2 - Create your private accounts file

cp accounts.json.template accounts.json

Edit accounts.json with your own server details:

{
  "primary-server": {
    "host": "server.example.com",
    "port": 2087,
    "user": "root",
    "token": "YOUR_WHM_API_TOKEN_HERE",
    "type": "whm",
    "label": "Primary WHM Server"
  },
  "staging-server": {
    "host": "staging.example.com",
    "port": 2087,
    "user": "root",
    "token": "YOUR_SECOND_WHM_API_TOKEN_HERE",
    "type": "whm",
    "label": "Staging WHM Server"
  }
}

Never commit accounts.json, API tokens, real hostnames, IP addresses, client names, or production account aliases.

Optional SSH Diagnostics and CSF

WHM API tokens can handle normal WHM/cPanel actions and cPHulk reporting. Live process diagnostics and CSF firewall management require SSH because they run fixed root-level commands such as ps, free, df, and csf.

Add these fields to an account only if you want those tools enabled:

{
  "primary-server": {
    "host": "server.example.com",
    "port": 2087,
    "user": "root",
    "token": "YOUR_WHM_API_TOKEN_HERE",
    "type": "whm",
    "ssh_enabled": true,
    "ssh_host": "server.example.com",
    "ssh_port": 22,
    "ssh_user": "root",
    "ssh_key_path": "C:\\Users\\you\\.ssh\\id_ed25519",
    "ssh_known_hosts": null
  }
}

The MCP does not expose arbitrary shell execution. SSH tools use fixed commands with validated inputs.


Client Setup

All clients need the same two values:

  • command: the Python executable inside .venv

  • args: the path to src/server.py

Use absolute paths in client configuration files.

Claude Desktop

Config file location:

OS

Path

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

Linux

~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ItchWHMMCP": {
      "command": "/absolute/path/to/ItchWHMMCP/.venv/bin/python",
      "args": ["/absolute/path/to/ItchWHMMCP/src/server.py"]
    }
  }
}

Cursor

Create or edit .cursor/mcp.json:

{
  "mcpServers": {
    "ItchWHMMCP": {
      "command": "/absolute/path/to/ItchWHMMCP/.venv/bin/python",
      "args": ["/absolute/path/to/ItchWHMMCP/src/server.py"]
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "ItchWHMMCP": {
      "command": "/absolute/path/to/ItchWHMMCP/.venv/bin/python",
      "args": ["/absolute/path/to/ItchWHMMCP/src/server.py"]
    }
  }
}

VS Code

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "ItchWHMMCP": {
      "type": "stdio",
      "command": "/absolute/path/to/ItchWHMMCP/.venv/bin/python",
      "args": ["/absolute/path/to/ItchWHMMCP/src/server.py"]
    }
  }
}

Cline

Open Cline settings > MCP Servers > Add Server, choose stdio, then enter:

  • Command: /absolute/path/to/ItchWHMMCP/.venv/bin/python

  • Args: /absolute/path/to/ItchWHMMCP/src/server.py

Continue

Add to ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "ItchWHMMCP",
      "command": "/absolute/path/to/ItchWHMMCP/.venv/bin/python",
      "args": ["/absolute/path/to/ItchWHMMCP/src/server.py"]
    }
  ]
}

Any Other stdio MCP Host

Use mcp.json in the project root as a reference:

{
  "name": "ItchWHMMCP",
  "version": "1.0.0",
  "transport": "stdio",
  "command": "python",
  "args": ["src/server.py"]
}

Windows users should replace .venv/bin/python with .venv\Scripts\python.exe.


Usage Examples

Once connected, ask your AI client naturally:

List all configured WHM accounts
Check server load on primary-server
Show DNS records for example.com on primary-server
Is Apache running on staging-server?
List email accounts for user demo on primary-server
Check disk usage across all accounts on primary-server
Suspend account demo-user on staging-server for policy violation
Show all SSL certificates on primary-server
What cron jobs does user demo have on primary-server?

Confirm the target server and account before running write operations such as account creation, suspension, termination, password changes, or service restarts.

Security and diagnostics examples:

Show top CPU processes on primary-server
Show a resource snapshot for primary-server
List recent cPHulk failed logins on primary-server
Check whether 203.0.113.10 is blocked in CSF on primary-server
Allow 203.0.113.10 in CSF on primary-server
Remove 203.0.113.10 from CSF on primary-server

Adding More Servers

Add another entry to accounts.json and restart your AI client. No code changes are required.


Project Structure

ItchWHMMCP/
|-- src/
|   |-- server.py          # MCP entry point
|   |-- accounts.py        # Multi-account loader
|   `-- tools.py           # WHM and cPanel tool definitions/handlers
|-- accounts.json.template # Safe template to copy from
|-- mcp.json               # Generic MCP client reference config
|-- pyproject.toml
|-- CONTRIBUTING.md
|-- LICENSE
`-- README.md

Local-only files such as accounts.json, .env, virtual environments, AI-agent notes, and personal client configuration should remain untracked.


Security Notes

  • WHM API tokens can be scoped and revoked per server from WHM.

  • accounts.json must stay local and untracked.

  • Avoid publishing real hostnames, IP addresses, account names, client names, API tokens, screenshots, or log output.

  • SSL verification is disabled by default for self-signed WHM certificates. If your server has a trusted certificate, enable verification in src/tools.py.

  • The MCP server runs locally as a subprocess of your AI client and does not open an inbound network port.

  • Review every destructive action before approving it in an AI client.


Contributing

Pull requests are welcome. Please read CONTRIBUTING.md before submitting changes.


License

MIT - see LICENSE for details.

Available Tools

31 tools
cpanel_bandwidth_usageC

Get bandwidth usage stats for a specific cPanel account

Inputs: account (required), cpanel_user (required).

cpanel_cron_listB

List all cron jobs configured for a cPanel account

Inputs: account (required), cpanel_user (required).

cpanel_disk_usageB

Get disk usage breakdown for a specific cPanel account

Inputs: account (required), cpanel_user (required).

cpanel_dns_recordsB

Get DNS zone records for a domain via cPanel UAPI

Inputs: account (required), cpanel_user (required), domain (required).

cpanel_email_createC

Create a new email account for a cPanel user

Inputs: account (required), cpanel_user (required), email (required), password (required), +1 more.

cpanel_email_listA

List all email accounts for a cPanel user's domain

Inputs: account (required), cpanel_user (required), domain (required).

cpanel_forwarders_listB

List all email forwarders for a cPanel user's domain

Inputs: account (required), cpanel_user (required), domain (required).

cpanel_mysql_listC

List MySQL databases and users for a cPanel account

Inputs: account (required), cpanel_user (required).

cpanel_ssl_checkC

Check SSL certificate status and expiry for a cPanel account's domains

Inputs: account (required), cpanel_user (required).

cpanel_subdomains_listB

List all subdomains and addon domains for a cPanel account

Inputs: account (required), cpanel_user (required).

list_accountsB

List all configured WHM/cPanel server accounts available in this MCP

Inputs: no named parameters.

whm_account_summaryA

Get detailed summary for a specific cPanel account (disk, bandwidth, emails, DBs)

Inputs: account (required), username (required).

whm_backup_listB

List available backups on the WHM server

Inputs: account (required).

whm_bandwidth_usageC

Get bandwidth usage statistics for all accounts or a specific account

Inputs: account (required), username.

whm_change_passwordC

Change password for a cPanel account

Inputs: account (required), username (required), password (required).

whm_create_accountC

Create a new cPanel hosting account on the WHM server

Inputs: account (required), username (required), domain (required), password (required), +2 more.

whm_disk_usageA

Get disk usage breakdown across all accounts on the server

Inputs: account (required).

whm_dns_list_zonesA

List all DNS zones managed by this WHM server

Inputs: account (required).

whm_dns_zone_recordsC

Get all DNS records for a specific zone/domain

Inputs: account (required), domain (required).

whm_list_accountsC

List all cPanel accounts on this WHM server with disk usage, domain, status

Inputs: account (required).

whm_list_ipsB

List all IP addresses on the server and their assignments

Inputs: account (required).

whm_list_packagesA

List all hosting packages/plans configured on the WHM server

Inputs: account (required).

whm_list_servicesA

Check status of all WHM services (Apache, MySQL, cPanel, SMTP, etc.)

Inputs: account (required).

whm_mysql_list_dbsB

List all MySQL databases on the server across all accounts

Inputs: account (required).

whm_restart_serviceA

Restart a specific service on the WHM server (apache, mysql, exim, etc.)

Inputs: account (required), service (required).

whm_server_infoA

Get WHM server information: hostname, OS, cPanel version, load, uptime

Inputs: account (required).

whm_server_loadA

Get real-time server load averages, memory usage, CPU, swap

Inputs: account (required).

whm_ssl_listC

List all SSL certificates installed on the server

Inputs: account (required).

whm_suspend_accountA

Suspend a cPanel account (disables login, web, email)

Inputs: account (required), username (required), reason.

whm_terminate_accountA

⚠️ PERMANENTLY DELETE a cPanel account and all its data

Inputs: account (required), username (required), confirm (required).

whm_unsuspend_accountB

Unsuspend/reactivate a suspended cPanel account

Inputs: account (required), username (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 31 tools

    Disambiguation5/5

    All tools have distinct purposes, clearly separated by cpanel_ and whm_ prefixes. No two tools have overlapping functionality; each targets a specific operation (e.g., bandwidth, cron, email, DNS) at either the account or server level.

    Naming Consistency5/5

    Naming follows a consistent pattern: lowercase snake_case with a clear prefix (cpanel_ or whm_) followed by an action and target (e.g., cpanel_bandwidth_usage, whm_create_account). No mixing of conventions.

    Tool Count4/5

    With 31 tools, the set is quite extensive but still reasonable for a full-featured WHM/cPanel management server. Each tool addresses a specific administrative task, and the count is justified by the breadth of server and account management needs.

    Completeness4/5

    Core hosting management operations are well covered: account CRUD, disk/bandwidth monitoring, email, DNS, SSL, services, and backups. Minor gaps exist (e.g., FTP management, database user manipulation), but the set covers most essential tasks without significant dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers