ngt-plesk-mcp
README.md
# ngt-plesk-mcp
**Server MCP remoto per Plesk**, sviluppato da [Next Gen Technologies Italia SRLS](https://n3xtgentech.it/).
Collega Claude (claude.ai, Claude Desktop, app mobile, Claude Code) al tuo server Plesk e gli permette di:
- **gestire gli stati**: attivare, sospendere o disattivare siti, subscription e clienti;
- **modificare i siti**: leggere, scrivere e modificare i file via SFTP, con **backup automatico** prima di ogni modifica;
- **fare tutto il resto**: qualsiasi endpoint della REST API di Plesk, qualsiasi `plesk bin` e comandi shell.
L'accesso è protetto da un **server OAuth 2.1 integrato**. L'amministratore approva ogni connessione con password e codice 2FA, e da un **pannello web** può revocare le connessioni, spegnere gli strumenti e consultare il registro delle attività. Non serve nessun provider di identità esterno.
[](https://github.com/n3xtgentech/ngt-plesk-mcp/actions/workflows/ci.yml)


> ⚠️ Questo server dà a chi si connette poteri da amministratore sul server Plesk (fino a root, se abiliti la shell). Leggi [Sicurezza](#sicurezza) prima di metterlo in produzione.
---
## Indice
- [Come funziona](#come-funziona)
- [Strumenti](#strumenti)
- [Requisiti](#requisiti)
- [Installazione](#installazione) — [systemd](#a-con-systemd-consigliata) · [Docker](#b-con-docker)
- [Collegare Claude](#collegare-claude)
- [Pannello di amministrazione](#pannello-di-amministrazione)
- [Configurazione](#configurazione)
- [Sicurezza](#sicurezza)
- [Sviluppo](#sviluppo)
- [Licenza](#licenza)
## Come funziona
```mermaid
flowchart LR
C[Claude<br/>claude.ai · Desktop · Code] -- "HTTPS · OAuth 2.1 Bearer" --> N[nginx di Plesk<br/>mcp.tuodominio.it]
N -- "127.0.0.1:8765" --> S[ngt-plesk-mcp]
S -- "REST API v2 + /cli · X-API-Key" --> P[Plesk :8443]
S -- "SFTP / SSH · chiave" --> H[(File dei siti<br/>/var/www/vhosts)]
A[Amministratore] -- "login + 2FA" --> S
```
1. Aggiungi il connettore su claude.ai con l'URL `https://mcp.tuodominio.it/mcp`.
2. Claude si registra da solo (RFC 7591) e ti porta alla pagina **Autorizza connessione** del tuo server.
3. Scegli i permessi e approvi con utente, password e codice 2FA.
4. Claude riceve un token valido solo per questo server. Il token dura 1 ora e viene rinnovato in automatico con refresh token a rotazione. Puoi revocare la connessione quando vuoi dal pannello.
Standard implementati:
- OAuth 2.1 con PKCE S256;
- Authorization Server Metadata (RFC 8414) e Protected Resource Metadata (RFC 9728);
- Resource Indicators (RFC 8707);
- revoca dei token (RFC 7009);
- parametro `iss` nella risposta di autorizzazione (RFC 9207);
- MCP Streamable HTTP, protocollo `2026-07-28`, con l'SDK ufficiale `mcp` 2.x.
## Strumenti
| Strumento | Cosa fa | Permesso |
|---|---|---|
| `plesk_server_info` · `plesk_list_domains` · `plesk_domain_info` · `plesk_list_customers` · `plesk_cli_commands` | Informazioni su server, domini, clienti | `plesk.read` |
| `plesk_set_site_status` | Sito `active` / `suspended` / `disabled` (`site --on/--suspend/--off`) | `plesk.write` |
| `plesk_set_subscription_status` | Subscription `active` / `suspended` (`subscription --webspace-on/--webspace-off`) | `plesk.write` |
| `plesk_set_customer_status` | Cliente `active` / `suspended` (`customer --on/--off`) | `plesk.write` |
| `plesk_cli` | Qualsiasi `plesk bin <utility>` (mail, dns, extension, wp-toolkit…) | `plesk.write` |
| `plesk_api_request` | Qualsiasi chiamata REST API v2. GET con lettura, il resto con scrittura | `plesk.read` / `plesk.write` |
| `files_list` · `files_read` · `files_list_backups` | Elenco cartelle, lettura file (testo o base64), backup | `plesk.read` |
| `files_write` · `files_edit` · `files_mkdir` · `files_move` · `files_delete` · `files_restore_backup` | Modifica dei file, con backup automatico | `plesk.write` |
| `server_exec` | Comando shell via SSH (wp-cli, chown, tar…) | `server.exec` |
Ogni strumento ha le annotazioni MCP (`readOnlyHint`, `destructiveHint`). Così Claude può chiedere conferma prima delle azioni distruttive.
Garanzie sui file:
- i percorsi sono confinati in `FILES_ROOT`, anche attraverso i symlink;
- prima di sovrascrivere, modificare o eliminare viene fatto un backup in `BACKUP_DIR`, che deve stare fuori dalle cartelle web;
- la scrittura è atomica (file temporaneo + rename) e mantiene proprietario, gruppo e permessi. I file nuovi prendono il proprietario dei file vicini, es. `utente:psacln`.
## Requisiti
- Plesk Obsidian per Linux con REST API attiva (lo è di default). Da provare prima su un server di test, vedi [CHANGELOG](CHANGELOG.md).
- Un sottodominio con certificato valido, es. `mcp.tuodominio.it` con Let's Encrypt.
- Python ≥ 3.11 (Ubuntu 24.04, Debian 12, AlmaLinux/Rocky 9 con `python3.11` o `python3.12`) oppure Docker.
- Accesso SSH a chiave per l'utente che gestirà i file. Di solito è `root`, sullo stesso server.
## Installazione
### Preparazione comune
```bash
# 1. Chiave API di Plesk, valida solo da localhost
sudo plesk bin secret_key --create -ip-address 127.0.0.1 -description "ngt-plesk-mcp"
# 2. Chiave SSH dedicata per file e comandi
sudo mkdir -p /etc/ngt-plesk-mcp
sudo ssh-keygen -t ed25519 -N "" -C ngt-plesk-mcp -f /etc/ngt-plesk-mcp/id_ed25519
echo "from=\"127.0.0.1\" $(sudo cat /etc/ngt-plesk-mcp/id_ed25519.pub)" | sudo tee -a /root/.ssh/authorized_keys
sudo sh -c 'ssh-keyscan -p 22 127.0.0.1 > /etc/ngt-plesk-mcp/known_hosts'
```
In `/etc/ssh/sshd_config` controlla che ci sia `PermitRootLogin prohibit-password`.
Il sottodominio `mcp.tuodominio.it` si crea in Plesk, con Let's Encrypt attivo. Poi vai in **Impostazioni Apache e nginx → Direttive aggiuntive di nginx** e incolla [`deploy/nginx-directives.conf`](deploy/nginx-directives.conf).
### A. Con systemd (consigliata)
```bash
sudo useradd --system --no-create-home --shell /usr/sbin/nologin ngt-plesk-mcp
sudo python3 -m venv /opt/ngt-plesk-mcp/venv
sudo /opt/ngt-plesk-mcp/venv/bin/pip install "ngt-plesk-mcp @ git+https://github.com/n3xtgentech/ngt-plesk-mcp@v1.0.0"
sudo cp .env.example /etc/ngt-plesk-mcp/ngt-plesk-mcp.env
sudo nano /etc/ngt-plesk-mcp/ngt-plesk-mcp.env # PUBLIC_URL, PLESK_URL, PLESK_API_KEY...
sudo chown -R ngt-plesk-mcp: /etc/ngt-plesk-mcp && sudo chmod 600 /etc/ngt-plesk-mcp/*
sudo cp deploy/ngt-plesk-mcp.service /etc/systemd/system/
sudo install -d -o ngt-plesk-mcp -g ngt-plesk-mcp -m 700 /var/lib/ngt-plesk-mcp
alias ngt='sudo -u ngt-plesk-mcp /opt/ngt-plesk-mcp/venv/bin/ngt-plesk-mcp --env-file /etc/ngt-plesk-mcp/ngt-plesk-mcp.env'
ngt admin init # crea l'amministratore: password + QR code da inquadrare con l'app di autenticazione
ngt check # verifica API Plesk, SSH e amministratore
sudo systemctl daemon-reload && sudo systemctl enable --now ngt-plesk-mcp
sudo journalctl -u ngt-plesk-mcp -f
```
### B. Con Docker
```bash
cp .env.example .env # con SFTP_KEY_FILE=/run/secrets/id_ed25519 e SFTP_KNOWN_HOSTS=/run/secrets/known_hosts
sudo chown 10001 /etc/ngt-plesk-mcp/id_ed25519 /etc/ngt-plesk-mcp/known_hosts
docker compose run --rm ngt-plesk-mcp admin init
docker compose up -d
docker compose exec ngt-plesk-mcp ngt-plesk-mcp check
```
L'immagine è `ghcr.io/n3xtgentech/ngt-plesk-mcp`: multi-arch, con SBOM e provenance firmata.
## Collegare Claude
- **claude.ai (Pro/Max)**: Impostazioni → Connettori → **Aggiungi connettore personalizzato**. Come URL metti `https://mcp.tuodominio.it/mcp`. Lascia vuote le impostazioni OAuth avanzate.
- **Team/Enterprise**: il proprietario dell'organizzazione lo aggiunge da Impostazioni organizzazione → Connettori.
- **Claude Code**: `claude mcp add --transport http plesk https://mcp.tuodominio.it/mcp`, poi `/mcp` per autenticarti.
Alla prima connessione si apre la pagina **Autorizza connessione** del tuo server. Togli i permessi che non vuoi concedere, ad esempio la shell, e approva con utente, password e codice 2FA.
Per i connettori personalizzati claude.ai permette di scegliere per ogni strumento tra "chiedi sempre" e "consenti". Consiglio "chiedi sempre" per gli strumenti segnati come distruttivi.
## Pannello di amministrazione
All'indirizzo `https://mcp.tuodominio.it/admin` (accesso con password + 2FA) puoi:
- vedere le **connessioni attive**: client, permessi, ultimo uso, scadenza. Puoi revocarne una o tutte;
- **attivare o disattivare ogni strumento**: un'eventuale disattivazione vale subito per tutte le connessioni;
- consultare il **registro attività**: chi ha fatto cosa e quando, filtrabile. Le password nei comandi sono oscurate;
- **verificare le connessioni** verso Plesk e SSH;
- eliminare i client registrati.
Comandi da riga di comando:
```
ngt-plesk-mcp admin init # crea l'amministratore (password + 2FA)
ngt-plesk-mcp admin passwd # cambia password
ngt-plesk-mcp admin reset-2fa # nuovo secondo fattore (telefono perso)
ngt-plesk-mcp revoke-all # revoca tutte le connessioni
ngt-plesk-mcp check # verifica la configurazione
ngt-plesk-mcp serve # avvia il server
```
## Configurazione
Tutto si configura con variabili d'ambiente: l'elenco completo, commentato, è in [`.env.example`](.env.example). Le principali:
| Variabile | Default | Note |
|---|---|---|
| `PUBLIC_URL` | — | URL HTTPS pubblico. È l'issuer OAuth e la risorsa è `PUBLIC_URL/mcp` |
| `PLESK_URL` / `PLESK_API_KEY` | — | REST API di Plesk |
| `SFTP_ENABLED` / `SHELL_ENABLED` | `true` | Spengono del tutto file e/o shell |
| `SFTP_USER` | `root` | Con un utente diverso da root si possono modificare solo i suoi file |
| `FILES_ROOT` / `BACKUP_DIR` | `/var/www/vhosts` / `/var/backups/ngt-plesk-mcp` | `BACKUP_DIR` deve stare fuori da `FILES_ROOT` |
| `ACCESS_TOKEN_TTL` / `REFRESH_TOKEN_TTL` | 1 h / 30 giorni | Durata dei token |
| `ALLOWED_REDIRECT_HOSTS` | `claude.ai,claude.com,localhost,127.0.0.1` | Client OAuth ammessi |
## Sicurezza
- **Un solo amministratore.** La password è salvata con hash Argon2id. Il 2FA TOTP è obbligatorio e un codice già usato non è accettato una seconda volta. Dopo 5 tentativi falliti l'IP viene bloccato per 15 minuti.
- **Token opachi**: nel database ci sono solo gli hash SHA-256. Ogni token è legato alla risorsa `PUBLIC_URL/mcp` (RFC 8707). Se un refresh token già usato viene ripresentato, l'intera connessione viene revocata.
- **Pannello**:
- CSRF su ogni form;
- cookie `__Host-` `HttpOnly` `SameSite=Strict`;
- CSP senza JavaScript;
- `frame-ancestors 'none'` contro il clickjacking.
- **Privilegio minimo**:
- concedi a ogni connessione solo i permessi che servono;
- spegni gli strumenti che non usi;
- con `SHELL_ENABLED=false` togli del tutto la shell;
- limita la chiave API a `127.0.0.1` e la chiave SSH con `from="127.0.0.1"`.
- I backup non vengono cancellati in automatico. Pianifica una pulizia, ad esempio `find /var/backups/ngt-plesk-mcp -name '*.bak' -mtime +30 -delete`.
Per segnalare una vulnerabilità segui [SECURITY.md](SECURITY.md).
## Sviluppo
```bash
uv sync # ambiente con dipendenze di sviluppo
uv run pytest # test (servono openssh-server per quelli su file/shell)
uv run ruff check . && uv run ruff format --check . && uv run mypy
uv run pre-commit install # controlli automatici a ogni commit
```
La struttura del codice è descritta in [docs/architecture.md](docs/architecture.md). Per contribuire leggi [CONTRIBUTING.md](CONTRIBUTING.md).
## Licenza
[Apache License 2.0](LICENSE) © 2026 Next Gen Technologies Italia SRLS — vedi [NOTICE](NOTICE).
Plesk è un marchio di WebPros International GmbH. Questo progetto non è affiliato a WebPros né a Plesk.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues