Skip to main content
Glama
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.

[![CI](https://github.com/n3xtgentech/ngt-plesk-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/n3xtgentech/ngt-plesk-mcp/actions/workflows/ci.yml)
![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)
![License](https://img.shields.io/badge/license-Apache--2.0-green)

> ⚠️ 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.