cPanel MCP Server

Serwer MCP (stdio) udostępniający agentowi narzędzia do zarządzania zwykłym kontem cPanel przez UAPI oraz serwerem cPanel & WHM przez WHM API 1. Jedna konfiguracja może zawierać wiele hostingów działających w trybie cpanel, whm albo both.

Serwer ma ponad 50 nazwanych operacji dla domen, DNS, poczty, baz MySQL, plików, cron, SSL, PHP, kopii zapasowych, kont hostingowych i usług. Opcjonalne narzędzia ogólne pozwalają wywołać funkcje dodane w nowszych wersjach cPanelu bez aktualizowania serwera MCP.

Wymagania i instalacja

• Node.js 20 lub nowszy,
• konto cPanel lub użytkownik WHM z tokenem API albo hasłem,
• dostęp sieciowy do portu 2083 (cPanel) lub 2087 (WHM).

npm install
npm run build
cp .example-connections.json connections.json
chmod 600 connections.json

Konfiguracja MCP

Wspólny plik connections.json ma dokładnie trzy poziomy: serwer → środowisko → logiczna nazwa konta. Dzięki temu jeden proces MCP może obsługiwać dowolną liczbę cPaneli i serwerów WHM, pogrupowanych np. według firmy i środowiska. Token lub hasło najlepiej wskazywać przez tokenEnv albo passwordEnv, dzięki czemu sekret nie znajduje się w pliku.

{
  "company": {
    "development": {
      "website": {
        "name": "Website DEV",
        "description": "Development cPanel account",
        "tags": ["website", "dev"],
        "baseUrl": "https://dev-panel.example.com",
        "username": "devuser",
        "passwordEnv": "CPANEL_DEV_PASSWORD",
        "mode": "cpanel"
      }
    },
    "production": {
      "website": {
        "name": "Website PROD",
        "tags": ["website", "prod", "critical"],
        "baseUrl": "https://panel.example.com",
        "username": "produser",
        "tokenEnv": "CPANEL_PROD_TOKEN",
        "mode": "cpanel",
        "cpanelPort": 2083,
        "timeoutMillis": 30000,
        "allowInsecureTls": false
      },
      "server-admin": {
        "name": "Production WHM",
        "baseUrl": "https://whm.example.com",
        "username": "root",
        "tokenEnv": "WHM_PROD_TOKEN",
        "mode": "whm",
        "whmPort": 2087
      }
    }
  }
}

Ten sam przykład znajduje się w .example-connections.json. Pokazuje konto DEV logowane hasłem i konta produkcyjne logowane tokenami. W wywołaniu narzędzia konto produkcyjne wybiera się przez server: "company", environment: "production", account: "website". Klucz account jest logiczną nazwą połączenia, a nie nazwą użytkownika cPanel.

Opcja	Argument CLI	Zmienna środowiskowa	Domyślna / znaczenie
plik połączeń	--config PATH	CPANEL_MCP_CONFIG	wymagany
tylko odczyt	--readonly true|false	CPANEL_MCP_READONLY	true
ogólne wywołania API	--allow-raw-api true|false	CPANEL_MCP_ALLOW_RAW_API	false

Argument CLI ma pierwszeństwo przed odpowiadającą mu zmienną. mode: "both" zakłada, że ten sam host, użytkownik i token mogą uwierzytelnić oba interfejsy. Gdy cPanel i WHM używają innych danych logowania, skonfiguruj je jako dwa konta logiczne. Plik connections.json znajduje się w .gitignore i powinien mieć uprawnienia 600.

Opcje konta w konfiguracji JSON

Pole	Wymagane	Znaczenie
baseUrl	tak	adres panelu; port jest zastępowany przez cpanelPort lub whmPort
username	tak	użytkownik cPanel albo WHM
tokenEnv / token	alternatywnie	nazwa zmiennej z tokenem albo token wpisany bezpośrednio
passwordEnv / password	alternatywnie	nazwa zmiennej z hasłem albo hasło wpisane bezpośrednio; wymaga HTTPS
mode	nie	cpanel, whm lub both; domyślnie cpanel
cpanelPort / whmPort	nie	domyślnie 2083 / 2087
timeoutMillis	nie	limit żądania, domyślnie 30 sekund
allowInsecureTls	nie	wyłącza weryfikację certyfikatu tylko dla tej instancji; domyślnie false
allowedCpanelModules	nie	allowlista modułów UAPI
allowedWhmFunctions	nie	allowlista funkcji WHM API 1

Każde konto musi mieć dokładnie jedną metodę uwierzytelnienia: token, tokenEnv, password albo passwordEnv. Preferowane są warianty *Env. Przy haśle serwer wysyła standardowy nagłówek HTTP Basic Authentication do cPanelu lub WHM; połączenie inne niż HTTPS jest odrzucane. allowInsecureTls: true nadal szyfruje ruch, ale nie weryfikuje certyfikatu i powinno być jedynie rozwiązaniem awaryjnym.

Uruchomienie bez klienta MCP

export CPANEL_DEV_PASSWORD='PASSWORD'
export CPANEL_PROD_TOKEN='TOKEN'
export WHM_PROD_TOKEN='TOKEN'
node dist/index.js --config ./connections.json --readonly true --allow-raw-api false

Proces czeka na komunikaty MCP na standardowym wejściu.

Visual Studio Code (GitHub Copilot)

Dodaj .vscode/mcp.json albo użyj polecenia MCP: Open User Configuration:

{
  "inputs": [{ "type": "promptString", "id": "cpanel-token", "description": "cPanel API token", "password": true }],
  "servers": {
    "cpanel": {
      "type": "stdio",
      "command": "/usr/bin/node",
      "args": ["/home/USER/src/cpanel-mcp-server/dist/index.js", "--config", "/home/USER/.config/cpanel-mcp/connections.json", "--readonly", "true"],
      "env": { "CPANEL_PROD_TOKEN": "${input:cpanel-token}" }
    }
  }
}

Visual Studio (GitHub Copilot)

Visual Studio odczytuje %USERPROFILE%\.mcp.json albo plik .mcp.json rozwiązania. Użyj tego samego obiektu serwera co powyżej, zmieniając command i ścieżkę skryptu na ścieżki Windows. Nie zapisuj prawdziwego tokenu w repozytorium.

Codex w Visual Studio Code

Codex CLI i rozszerzenie IDE współdzielą ~/.codex/config.toml:

[mcp_servers.cpanel]
command = "/usr/bin/node"
args = ["/home/USER/src/cpanel-mcp-server/dist/index.js", "--config", "/home/USER/.config/cpanel-mcp/connections.json", "--readonly", "true"]
env = { CPANEL_PROD_TOKEN = "TOKEN" }
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled = true
default_tools_approval_mode = "writes"

PhpStorm (JetBrains AI Assistant)

Otwórz Settings → Tools → AI Assistant → Model Context Protocol (MCP), dodaj połączenie STDIO i użyj konfiguracji mcpServers analogicznej do przykładu VS Code. Ustaw bezwzględne ścieżki do dist/index.js i connections.json oraz zmienne z sekretami wskazane przez tokenEnv lub passwordEnv.

Codex w PhpStorm

Skonfiguruj serwer w JetBrains AI Assistant, a podczas aktywowania agenta Codex włącz Pass custom MCP servers. Alternatywnie uruchom Codex CLI z konfiguracją TOML z poprzedniej sekcji.

Wygasły lub niezaufany certyfikat TLS

Najbezpieczniej zainstalować prawidłowy certyfikat panelu. Awaryjnie można ustawić allowInsecureTls: true tylko dla konkretnej instancji. Nie wyłącza to TLS, ale wyłącza weryfikację tożsamości serwera i ułatwia atak man-in-the-middle.

Healthcheck

healthcheck z deep=false sprawdza proces i konfigurację bez połączenia z hostingiem. deep=true odpytuje każde połączenie przez UAPI Variables::get_user_information lub WHM version. Wynik identyfikuje je przez server, environment i account, ale nie zawiera tokenów.

Narzędzia

Każde narzędzie wskazuje połączenie przez server, environment i account oraz przyjmuje obiekt parameters zgodny z parametrami odpowiedniej funkcji cPanel. list_connections pokazuje wszystkie trzy poziomy i metadane bez sekretów. Zwracany jest JSON znormalizowany z typowych kopert UAPI/WHM.

cPanel UAPI

• konto, domeny i statystyki: cpanel_get_account_information, cpanel_list_domains, cpanel_get_domain_data, cpanel_get_resource_usage,
• DNS: listowanie, dodawanie, edycja i usuwanie rekordów,
• poczta: konta, hasła, limity, forwardery i autorespondery,
• MySQL: bazy, użytkownicy i uprawnienia,
• pliki: listowanie, odczyt, zapis, tworzenie katalogów i usuwanie,
• cron, certyfikaty SSL, wersje PHP oraz pełny backup konta.

WHM API 1

• wersja serwera, lista i podsumowanie kont,
• tworzenie, modyfikacja, zawieszanie, odwieszanie i usuwanie kont,
• pakiety hostingowe,
• strefy DNS i rekordy,
• SSL vhosty oraz instalacja certyfikatów,
• status i restart usług, wykorzystanie dysku oraz tymczasowe sesje użytkowników.

Pełną listę nazwanych narzędzi zawiera src/catalog.ts. Ich parameters pozostają elastyczne, ponieważ dostępność i argumenty funkcji zależą od wersji cPanelu, profilu serwera i uprawnień tokenu.

Funkcje spoza katalogu

cpanel_uapi_call i whm_api_call są dostępne dopiero po ustawieniu CPANEL_MCP_ALLOW_RAW_API=true. Wymagają jawnego mutation: true|false; mutacje nadal respektują tryb READONLY. Allowlisty instancji obowiązują również te narzędzia.

READONLY i bezpieczeństwo

Serwer domyślnie uruchamia się z READONLY=true. Nazwane mutacje oraz ogólne wywołania zadeklarowane jako mutacje są wtedy blokowane przed wysłaniem żądania.

• preferuj tokeny o najmniejszych niezbędnych uprawnieniach; jeśli panel nie udostępnia tokenów, przechowuj hasło przez passwordEnv,
• osobno konfiguruj cPanel i WHM, jeśli mają różne dane logowania,
• stosuj allowedCpanelModules i allowedWhmFunctions w środowiskach produkcyjnych,
• pozostaw ogólne API wyłączone, jeśli nazwane narzędzia wystarczają,
• wymagaj potwierdzenia klienta MCP dla narzędzi usuwających konta, pliki, DNS i bazy,
• nie zapisuj hasła cPanel/WHM, haseł skrzynek, baz ani kluczy prywatnych w repozytorium lub parametrach narzędzi.

Uwaga: cPanel nie udostępnia metadanych określających, czy dowolna funkcja API modyfikuje stan. W ogólnych narzędziach prawidłowa wartość mutation jest odpowiedzialnością wywołującego; allowlisty zapewniają dodatkową granicę bezpieczeństwa.

Wartości ograniczone parametrów

Nazwy modułów, funkcji i parametrów API są walidowane. Ścieżka oraz host żądania są konstruowane wyłącznie z konfiguracji, więc parametry narzędzia nie mogą przekierować żądania na inny serwer. Timeout ma maksymalnie 300 sekund. Tokeny nie są zwracane przez list_connections, błędy ani healthcheck.

Testy

npm run check

Testy jednostkowe nie wymagają prawdziwego serwera cPanel. Sprawdzają adresy UAPI/WHM, schemat autoryzacji, dane formularzy, tryby API, allowlisty, ochronę sekretów, domyślne ustawienia i pokrycie katalogu operacji.

Test integracyjny z hostingiem należy rozpocząć od --readonly true, healthcheck(deep=true) i narzędzi listujących. Konkretne funkcje mogą być niedostępne zależnie od licencji, wersji, profilu WHM i uprawnień konta.