Skip to main content
Glama

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 without npm 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 (0 packages): Built strictly with Node.js built-in modules (node:http, node:crypto, node:fs, node:readline, native fetch). Never gets stuck on npm install or ECONNRESET.

  • Works on Any Shared cPanel Hosting: Connects from your machine directly to cPanel's encrypted UAPI on port 2083 using a revocable API Token (no SSH required).

  • 100% Private & Local: Your credentials stay on your computer (config.json is 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_file call snapshots the previous version into .claude_backups/ before saving.

    • Sensitive File Protection: Configurable BLOCKED_FILES list (.env, wp-config.php, etc.).


Related MCP server: whm-mcp-server

Included Tools (10 Capabilities)

Tool

Description

list_files

List files & directories (including dotfiles, permissions, and human-readable sizes)

read_file

Read the full content of any text/code/config file

write_file

Create or update files with automatic .claude_backups versioning

create_folder

Create new directories

delete_item

Move items to cPanel Trash (default) or permanently delete

rename_or_move

Rename, move, or copy files and folders

chmod_item

Change file/folder permissions (0644, 0755, etc.)

zip_items

Compress files/folders into a .zip archive directly on the server

unzip_item

Extract .zip archives directly on the server

cpanel_uapi

Call any official cPanel UAPI module (Mysql, Cron, SSL, SubDomain, Email)


Step 1: Get Your cPanel Credentials & API Token

  1. Log in to your cPanel dashboard.

  2. In the right-hand General Information panel, note down Current User and Home Directory.

  3. Copy your direct server hostname on port 2083 from 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 2083 and causes connection timeouts.

  4. 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 .htaccess or .env files.


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:

  1. Start the local HTTP bridge in CMD / Terminal:

    node C:\mcp\cpanel-mcp\index.js --http

    (Copy the printed Bearer Token or set your own HTTP_API_KEY in config.json.)

  2. Expose port 3000 securely using Cloudflare Tunnel (free, no account needed):

    cloudflared tunnel --url http://localhost:3000
  3. In ChatGPT (chatgpt.com), go to Explore GPTs → Create → Configure:

    • Paste the contents of skill/SKILL.md into 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.js

3. Claude Desktop (Free Account)

  1. 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)

  2. Run install.bat (Windows) or ./install.sh (macOS/Linux).

  3. 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
gemini

5. 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
claude

Troubleshooting

  • fetch failed or ConnectTimeoutError on port 2083:

    1. Replace any Cloudflare-proxied domain in CPANEL_HOST with your direct server hostname.

    2. Toggle your VPN on/off (some hosts restrict port 2083 by IP region) and run node test-connection.js.

  • SSL Certificate Error on port 2083: Set "ALLOW_INSECURE_SSL": true in config.json.

  • Claude Desktop doesn't see cpanel tools: Make sure you are in the desktop app (not claude.ai in the browser), end all Claude processes in Task Manager, and check ☰ → File → Settings → Developer → Edit Config.

Available Tools

10 tools
chmod_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

    A3.5/5.0

    Scored across 10 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      13
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      -