cpanel-mcp
# 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)](README.fa.md)**
---
## 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.).
---
## 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:
```json
{
"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](https://nodejs.org/) 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:
```cmd
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):
```cmd
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:
```cmd
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):
```cmd
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)
```cmd
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`):
```json
{
"mcpServers": {
"cpanel": {
"command": "node",
"args": ["C:\\mcp\\cpanel-mcp\\index.js"]
}
}
}
```
### 6. Claude Code CLI (Requires Pro/Max Plan or API Key)
```cmd
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**.
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.