ItchWHMMCP
ItchWHMMCP is a local MCP server that enables AI clients to manage WHM/cPanel servers through 30+ tools, supporting multiple WHM accounts from a private configuration file.
Server Health & Information
Get server load averages, memory, CPU, uptime, OS, and cPanel version
Real-time process snapshots and disk/memory checks (via optional SSH)
Account Management
List, create, suspend, unsuspend, change password for, and permanently terminate cPanel accounts
Get detailed account summaries and list available hosting packages/plans
Service Management
Check status and restart services (Apache, MySQL, Exim, FTP, cpsrvd)
DNS Management
List all DNS zones and query specific DNS records per domain (WHM and cPanel levels)
Email Management
List and create email accounts; list email forwarders for cPanel users
Database Management
List all MySQL databases server-wide (WHM) and per cPanel account, including database users
SSL Certificates
List all installed SSL certificates server-wide and check certificate status/expiry per domain
Bandwidth & Disk Usage
Get server-wide and per-account bandwidth usage statistics and detailed disk usage breakdowns
Cron Jobs & Domains
List cron jobs, subdomains, and addon domains for specific cPanel accounts
Security (Optional)
cPHulk brute-force reporting and unblock; CSF firewall IP allow/deny/remove
Other
List server IP addresses and their assignments
List available backups on the WHM server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ItchWHMMCP Check the server load and uptime on primary-server"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Full support | |
| Full support | |
| Full support | |
| Requires MCP support/extension | |
MCP settings UI | Full support | |
| 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 |
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 ItchWHMMCP2. Create a virtual environment
macOS / Linux:
python3 -m venv .venv
source .venv/bin/activateWindows:
python -m venv .venv
.venv\Scripts\Activate.ps13. Install dependencies
pip install mcp httpx asyncsshConfiguration
Step 1 - Generate WHM API Tokens
For each server you want to connect:
Log in to WHM.
Open Development > Manage API Tokens.
Generate a token for this MCP server.
Copy the token immediately; WHM shows it only once.
Repeat for each server you want to manage.
Step 2 - Create your private accounts file
cp accounts.json.template accounts.jsonEdit 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.venvargs: the path tosrc/server.py
Use absolute paths in client configuration files.
Claude Desktop
Config file location:
OS | Path |
macOS |
|
Windows |
|
Linux |
|
{
"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/pythonArgs:
/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-serverAdding 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.mdLocal-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.jsonmust 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 toolscpanel_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
Scored across 31 tools
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 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.
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.
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
Related MCP Connectors
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for building and testing AI agents with multi-model experimentation and insights.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Related MCP Servers
- AlicenseAqualityDmaintenanceA complete MCP server enabling AI assistants to manage cPanel hosting through natural language, including file, database, email, subdomain, and system operations.161MIT
- AlicenseBqualityCmaintenanceA comprehensive MCP server for managing cPanel hosting accounts through AI assistants. It supports DNS, email (DKIM/SPF), databases, domains, SSL, PHP, cron jobs, security, Git deployment, and more.10027ISC
- AlicenseNot gradedqualityFmaintenanceA comprehensive MCP server for managing cPanel web hosting accounts via UAPI, enabling file, database, email, domain, cron, backup, and system monitoring operations.32 npm3MIT
- AlicenseAqualityDmaintenanceMCP server for managing cPanel hosting accounts via UAPI. Enables domains, DNS, email, MySQL, file management, and arbitrary UAPI calls through natural language.1637 npmMIT