cpanel-mcp
Provides tools for managing files and folders on cPanel hosting—listing, reading, writing with automatic backups, creating folders, deleting, renaming/moving, changing permissions, and zipping/unzipping—plus a generic cPanel UAPI tool for calling modules such as MySQL, Cron, SSL, SubDomain, and Email.
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., "@cpanel-mcp list the files in my public_html folder with permissions and sizes"
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.
cpanel-mcp (Universal Edition)
Zero-Dependency Local MCP & OpenAPI Server for cPanel Hosting
Connect ChatGPT (Web & Desktop), Claude (Desktop & Code), Gemini CLI, Cursor, VS Code Copilot, or Local LLMs (LM Studio / Ollama) directly to your cPanel hosting—without SSH, without uploading PHP backdoors, and withoutnpm install.
🌐 راهنمای کامل فارسی (Persian Guide)
Why cpanel-mcp?
Universal AI Support: Works natively over MCP (
stdio& HTTP) and OpenAPI 3.1 (for ChatGPT Custom GPT Actions).Zero Dependencies (
0packages): Built strictly with Node.js built-in modules (node:http,node:crypto,node:fs,node:readline, nativefetch). Never gets stuck onnpm installorECONNRESET.Works on Any Shared cPanel Hosting: Connects from your machine directly to cPanel's encrypted UAPI on port
2083using a revocable API Token (no SSH required).100% Private & Local: Your credentials stay on your computer (
config.jsonis git-ignored). Nothing is uploaded to your public web root.Built-in Safety Guardrails:
Path Jail (
ALLOWED_ROOT): Blocks directory traversal outside your configured root folder.Automatic Backups: Every
write_filecall snapshots the previous version into.claude_backups/before saving.Sensitive File Protection: Configurable
BLOCKED_FILESlist (.env,wp-config.php, etc.).
Related MCP server: whm-mcp-server
Included Tools (10 Capabilities)
Tool | Description |
| List files & directories (including dotfiles, permissions, and human-readable sizes) |
| Read the full content of any text/code/config file |
| Create or update files with automatic |
| Create new directories |
| Move items to cPanel Trash (default) or permanently delete |
| Rename, move, or copy files and folders |
| Change file/folder permissions ( |
| Compress files/folders into a |
| Extract |
| Call any official cPanel UAPI module ( |
Step 1: Get Your cPanel Credentials & API Token
Log in to your cPanel dashboard.
In the right-hand General Information panel, note down Current User and Home Directory.
Copy your direct server hostname on port
2083from the browser address bar (e.g.,https://server12.yourhost.com:2083).Important: Do not use your domain name if it is proxied through Cloudflare, because Cloudflare blocks port
2083and causes connection timeouts.Go to Security → Manage API Tokens, create a new token, and copy it.
Step 2: Configure config.json
Copy config.example.json to config.json and fill in your credentials:
{
"CPANEL_HOST": "https://server12.yourhost.com:2083",
"CPANEL_USER": "myuser",
"CPANEL_TOKEN": "YOUR_CPANEL_API_TOKEN",
"ALLOWED_ROOT": "/home/myuser/public_html",
"BLOCKED_FILES": [
".env",
"wp-config.php",
"config.php",
".htaccess"
],
"ALLOW_INSECURE_SSL": false,
"HTTP_PORT": 3000,
"HTTP_API_KEY": "CHANGE_THIS_TO_A_RANDOM_SECRET_KEY"
}Tip for Full Hosting Access: Set
"ALLOWED_ROOT": "/home/myuser"and"BLOCKED_FILES": []if you want the AI to manage all domains/subdomains and edit.htaccessor.envfiles.
Step 3: Connect to Any AI Client
Prerequisite: Node.js v18 or higher (
node -v).
1. ChatGPT Web (chatgpt.com Custom GPTs)
cpanel-mcp includes a built-in OpenAPI 3.1 HTTP server (--http) with Bearer token authentication:
Start the local HTTP bridge in CMD / Terminal:
node C:\mcp\cpanel-mcp\index.js --http(Copy the printed
Bearer Tokenor set your ownHTTP_API_KEYinconfig.json.)Expose port
3000securely using Cloudflare Tunnel (free, no account needed):cloudflared tunnel --url http://localhost:3000In ChatGPT (
chatgpt.com), go to Explore GPTs → Create → Configure:Paste the contents of
skill/SKILL.mdinto Instructions.Click Create new action → Import from URL and enter
<YOUR_TRYCLOUDFLARE_URL>/openapi.json.Under Authentication, choose API Key → Bearer and paste your
Bearer Token.
2. OpenAI Codex CLI & ChatGPT Desktop
Register cpanel-mcp as a local stdio MCP server:
codex mcp add cpanel -- node C:\mcp\cpanel-mcp\index.js3. Claude Desktop (Free Account)
Install Claude Desktop via Windows CMD (if not installed):
curl -L "https://claude.ai/api/desktop/win32/x64/exe/latest/redirect" -o "%USERPROFILE%\Downloads\Claude-Setup-x64.exe" start "" "%USERPROFILE%\Downloads\Claude-Setup-x64.exe"(Or via
winget install -e --id Anthropic.Claude)Run
install.bat(Windows) or./install.sh(macOS/Linux).Fully quit Claude Desktop from the System Tray (
Quit) and reopen it.
4. Gemini CLI (Free with Google Account)
npm install -g @google/gemini-cli
gemini mcp add cpanel node C:\mcp\cpanel-mcp\index.js
gemini5. Cursor, Windsurf, VS Code Copilot & LM Studio
Add this snippet to your editor's MCP configuration (mcp.json / cline_mcp_settings.json / LM Studio mcp.json):
{
"mcpServers": {
"cpanel": {
"command": "node",
"args": ["C:\\mcp\\cpanel-mcp\\index.js"]
}
}
}6. Claude Code CLI (Requires Pro/Max Plan or API Key)
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://claude.ai/install.ps1 | iex"
set "PATH=%USERPROFILE%\.local\bin;%APPDATA%\npm;%PATH%"
claude mcp add --scope user cpanel -- node C:\mcp\cpanel-mcp\index.js
claudeTroubleshooting
fetch failedorConnectTimeoutErroron port2083:Replace any Cloudflare-proxied domain in
CPANEL_HOSTwith your direct server hostname.Toggle your VPN on/off (some hosts restrict port
2083by IP region) and runnode test-connection.js.
SSL Certificate Error on port
2083: Set"ALLOW_INSECURE_SSL": trueinconfig.json.Claude Desktop doesn't see
cpaneltools: Make sure you are in the desktop app (notclaude.aiin the browser), end all Claude processes in Task Manager, and check☰→ File → Settings → Developer → Edit Config.
Available Tools
10 toolschmod_itemB
Change file or directory permissions (chmod) on the cPanel server (e.g., 0644 or 0755).
Inputs: path (required), permissions (required).
cpanel_uapiC
Execute any official cPanel UAPI module function (e.g., Mysql, Cron, SSL, SubDomain, Email).
Inputs: func (required), module (required), params.
create_folderC
Create a new directory inside ALLOWED_ROOT.
Inputs: name (required), dir.
delete_itemB
Move a file or directory to cPanel Trash, or permanently delete it.
Inputs: path (required), permanent.
list_filesA
List all files and directories (including dotfiles, permissions, and sizes) inside a cPanel directory.
Inputs: dir.
read_fileB
Read the full text content of a file on the cPanel server.
Inputs: file (required), dir.
rename_or_moveC
Rename, move, or copy a file or directory on the cPanel server.
Inputs: source (required), operation (required), destination (required).
unzip_itemC
Extract a ZIP archive directly on the cPanel server.
Inputs: zip_path (required), dest_dir.
write_fileA
Create or overwrite a file on the cPanel server (automatically saves a backup in .claude_backups first).
Inputs: file (required), content (required), dir.
zip_itemsB
Compress one or more files/folders into a ZIP archive directly on the server.
Inputs: sources (required), dest_zip (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools target a distinct file operation (list, read, write, delete, chmod, zip/unzip) and are easy to tell apart. Minor overlap exists: write_file can implicitly create paths that create_folder also handles, rename_or_move secretly also copies, and cpanel_uapi's Fileman module can duplicate any of these file operations.
The set is predominantly consistent verb_noun snake_case (list_files, read_file, create_folder, delete_item, chmod_item). Deviations are small: cpanel_uapi is noun-only with no verb, rename_or_move uses a compound verb, and zip_items/unzip_item are asymmetrically pluralized.
Ten tools is a well-scoped size for a file-management server, with each tool covering a distinct primary operation. The single generic UAPI escape hatch avoids bloating the surface with dozens of cPanel-domain tools.
The core file lifecycle is covered: list, read, write, create, delete, move/copy, chmod, and archive round-trip, backed by UAPI for anything else. Gaps are minor (no file search/grep, no append or stat/exists check, no upload/download), but agents can work around them via read/write or UAPI.
Maintenance
Related MCP Connectors
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Hosting run by your AI agent: publish websites, apps, databases, domains and email from chat.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
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
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to manage WHM hosting accounts and server administration tasks including account management, server stats, updates, SSL, backups, and email through a secure API.13ISC
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage cPanel hosting accounts including DNS, email, databases, SSL, files, security, and more through natural language using cPanel's UAPI and API2.ISC
- FlicenseNot gradedqualityCmaintenanceEnables an AI assistant to read, search, send, reply to, forward, and organize cPanel mailbox messages over IMAP and SMTP, including folders, attachments, drafts, and flags, plus calendar event management via CalDAV when configured. Runs as a local stdio server so each user connects with their own credentials.-