clickup-custom-mcp

Server MCP su stdio per gestire task e subtask di una sola lista ClickUp configurata, con una allowlist rigida delle proprietà scrivibili.

Token, ID e nome della lista vengono letti esclusivamente da variabili d’ambiente a runtime. Il pacchetto non contiene credenziali né identificativi di workspace, spazi, cartelle, liste o task.

Perimetro

Il server può creare e modificare soltanto queste colonne:

• Nome
• Stato, limitato agli stati effettivamente disponibili nella lista
• Assegnatari
• Priorità
• Data scadenza
• Data inizio
• CRM, che deve essere un Custom Field ClickUp di tipo url

Gli stati disponibili vengono letti dalla configurazione reale della lista. In creazione e aggiornamento il valore richiesto viene risolto senza distinzione fra maiuscole e minuscole e inviato a ClickUp con il nome canonico. ID, tipo, parentId e URL ClickUp restano metadati strutturali in sola lettura.

Non esistono tool o parametri per descrizione, commenti, tag, watcher, stime, altri Custom Field, spostamento, parent, archiviazione o cancellazione. Non è esposto alcun passthrough verso l’API ClickUp.

Negli aggiornamenti, crm: null svuota CRM e assegnatariIds: [] rimuove gli assegnatari. La rimozione di Priorità, Data scadenza e Data inizio non è esposta: l’API v2 pubblica documenta per quei campi soltanto valori interi, non null.

Ogni operazione:

1. verifica che CLICKUP_LIST_ID punti esattamente a CLICKUP_LIST_NAME;
2. verifica che il campo CRM esista e sia di tipo URL;
3. valida l’eventuale stato richiesto contro gli stati disponibili nella lista;
4. per le scritture su task esistenti, verifica che la task appartenga alla lista configurata;
5. rilegge il risultato e segnala campi non confermati o cambiamenti inattesi.

Tool

• opzioni_lista — lista, stati, assegnatari, priorità e allowlist.
• elenca_task_lista — task e subtask, paginate.
• cerca_task_lista — ricerca per nome e filtri combinabili di Stato e assegnatario.
• leggi_task_lista — task, proprietà consentite e subtask.
• crea_task_lista — nuova task nella lista configurata.
• crea_subtask_lista — nuova subtask sotto un parent verificato.
• aggiorna_task_lista — aggiornamento parziale delle sole sette colonne.

Tutti i tool di scrittura accettano dry_run: true.

cerca_task_lista accetta testo, stato e assegnatarioId, richiedendo almeno uno dei tre. Quando sono presenti più criteri vengono combinati con logica AND. Stato e assegnatario sono validati contro opzioni_lista e inviati anche come filtri server-side all’API ClickUp.

Configurazione ClickUp

1. Crea un token ClickUp adatto all’ambiente in cui eseguirai il server.
2. Copia il link della lista autorizzata e ricava il numero dopo /li/.
3. Verifica che la lista abbia un solo Custom Field chiamato esattamente CRM, di tipo Website / URL, applicabile alle task standard.

Il token ha i permessi dell’account associato: trattalo come un segreto e conservalo nel secret store del gateway. Per difesa in profondità, usa un account tecnico o guest che abbia accesso soltanto alla lista autorizzata.

Avvio

Richiede Node.js 20 o successivo.

Configura il gateway MCP con il comando:

npx -y [email protected]

Variabili obbligatorie:

{
  "CLICKUP_API_TOKEN": "<CLICKUP_TOKEN>",
  "CLICKUP_LIST_ID": "<CLICKUP_LIST_ID>",
  "CLICKUP_LIST_NAME": "<CLICKUP_LIST_NAME>"
}

Variabili opzionali:

• CLICKUP_CRM_FIELD_ID: UUID del campo CRM. Se omesso viene trovato per nome.
• CLICKUP_TIMEZONE: fuso IANA usato per le date, default Europe/Rome.
• CLICKUP_AUTH_MODE: auto (default), personal oppure oauth.
• CLICKUP_TIMEOUT_MS: timeout della singola chiamata HTTP, default 20000.
• CLICKUP_DEADLINE_MS: deadline complessiva del processo, default 90000 (massimo 105000).
• CLICKUP_MAX_RETRIES: retry su rete, 429 e 5xx, default 2.

CLICKUP_LIST_NAME è obbligatorio e viene verificato a ogni processo. Un ID che punta a una lista con nome diverso blocca anche i dry-run.

Sviluppo

npm install
npm test
npm pack --dry-run

Il pacchetto npm include solo i file di runtime dichiarati in package.json, oltre ai metadati e ai documenti aggiunti automaticamente da npm.