clickup-mcp-full

Ein ClickUp-MCP-Server, der einen ganzen verschachtelten Unteraufgabenbaum in einem einzigen Aufruf lesen kann.

Er kapselt @twofeetup/clickup-mcp, statt ihn zu forken, sodass Upstream-Fixes mit einem Abhängigkeits-Update eintreffen. Zusätzlich zu diesem Server fügt er get_task_tree hinzu, schreibt eine Tool-Beschreibung um, die kleinere Modelle zuverlässig in die Irre führt, und legt einen sinnvollen Standard-Toolsatz fest.

Warum

Der einzige Weg des Upstreams zu Unteraufgaben ist search_tasks mit include_subtasks, was GET /task/{id}?subtasks=true aufruft und vollständige Aufgabenobjekte nur für die direkten Kinder zurückgibt. Bei einer Aufgabe mit fünfzig Unteraufgaben, die mehrere Ebenen tief verschachtelt sind, ist das sowohl unvollständig als auch verheerend für den Kontextfenster eines Agents. Die Alternative – eine Anfrage pro Knoten – ist noch schlimmer.

get_task_tree durchläuft stattdessen einmal die enthaltende Liste. ClickUps GET /list/{id}/task?subtasks=true gibt jede Aufgabe in der Liste zusammen mit ihrem parent-Zeiger zurück, sodass der Baum lokal wieder zusammengesetzt wird: insgesamt zwei Anfragen, unabhängig von Tiefe oder Breite, und die Ausgabe ist eine kompakte Zeile pro Aufgabe.

Task tree for 86capt3b: 23 task(s) including the root.
Statuses: in progress: 3, open: 14, complete: 6
List: Q3 Delivery

86capt3b  [in progress]  Migrate billing service  <ivan>
  86captk1  [complete]  Audit current schema  <olena>
  86captk2  [in progress]  Write migration scripts  <ivan>
    86captm7  [open]  Handle partial refunds
    86captm8  [open]  Backfill historical rows
  86captk3  [open]  Cutover plan

Related MCP server: ClickUp MCP

Installation

Nichts zu klonen oder zu bauen. Weisen Sie Ihren Agenten auf das Paket, und es wird beim ersten Start abgerufen.

Claude Code

claude mcp add clickup_full_local \
  --env CLICKUP_API_KEY=pk_your_token \
  --env CLICKUP_TEAM_ID=9012345678 \
  -- npx -y github:breckenreed/clickup-mcp-full

Claude Desktop, Cursor, Windsurf oder jeder Client, der mcpServers-JSON verwendet

{
  "mcpServers": {
    "clickup_full_local": {
      "command": "npx",
      "args": ["-y", "github:breckenreed/clickup-mcp-full"],
      "env": {
        "CLICKUP_API_KEY": "pk_your_token",
        "CLICKUP_TEAM_ID": "9012345678"
      }
    }
  }
}

Hermes (~/.hermes/config.yaml)

mcp_servers:
  clickup_full_local:
    command: npx
    args: ["-y", "github:breckenreed/clickup-mcp-full"]
    env:
      CLICKUP_API_KEY: "${CLICKUP_API_KEY}"
      CLICKUP_TEAM_ID: "${CLICKUP_TEAM_ID}"
    connect_timeout: 60
    keepalive_interval: 60
    idle_timeout_seconds: 1800

Globale Installation, falls Sie nicht bei jedem Start von GitHub auflösen möchten:

npm install -g github:breckenreed/clickup-mcp-full

Verwenden Sie dann clickup-mcp-full als Befehl ohne Argumente.

Anmeldedaten

Ein ClickUp-Personaltoken hat keine eigenen Bereiche. Es handelt im Namen des Benutzers, der es erstellt hat, und erbt dessen Berechtigungen. Wenn Sie also einen Agenten möchten, der nicht schreiben kann, erstellen Sie das Token unter einem Nur-Lese-ClickUp-Konto, statt sich auf die Tool-Auswahl zu verlassen.

Tools

Upstream liefert außerdem attach_file_to_task, das eine lokale Datei in ClickUp hochlädt. Es ist hier standardmäßig deaktiviert: Für einen Agenten, der ohne Bestätigung pro Aktion läuft, wird jede Prompt-Injection, die der Agent liest, zu einem Datenabflusspfad. Aktivieren Sie es bewusst, wenn Sie es benötigen:

ENABLED_TOOLS=get_workspace_hierarchy,search_tasks,manage_task,task_comments,get_container,manage_container,find_members,operate_tags,task_time_tracking,attach_file_to_task

Optionen

Erhöhen Sie REQUEST_SPACING in einem gemeinsam genutzten Arbeitsbereich. Der Standardwert erlaubt etwa zehn Anfragen pro Sekunde, während das Limit von ClickUp pro Token bei den meisten Plänen bei ungefähr 100 pro Minute liegt. Das Limit wird auf das Token angerechnet, nicht auf das Tool, sodass ein Agent, das es erschöpft, auch jede andere Integration unter demselben Token unterbricht. 700 hält Sie unter einem Limit von 100 pro Minute.

Hinweise zum Verhalten

Unteraufgaben in einer anderen Liste. Der Baum wird erstellt, indem die Liste durchlaufen wird, die die Wurzelaufgabe enthält. Wenn Ihr Arbeitsbereich Unteraufgaben in einer anderen Liste als ihre übergeordnete Aufgabe platziert, werden diese nicht angezeigt, und der Server fällt auf die direkten Kinder zurück, die der Aufgaben-Endpunkt meldet. Öffnen Sie ein Issue, falls Sie darauf stoßen und es wichtig ist.

search_tasks-Beschreibungen. Die Upstream-Beschreibung („Funktioniert auf 3 Arten") führt kleinere Modelle dazu, eine einfache ID wie 86capt3b in customTaskId einzutragen, das nur für präfixierte IDs wie DEV-123 gedacht ist. Ein solcher Aufruf fällt in den Zweig der Arbeitsbereichssuche und schlägt mit „Mindestens ein Filterparameter ist erforderlich" fehl – ein Fehler, der das falsche Problem benennt, woraufhin das Modell dazu neigt, Filter zu erfinden, statt das Feld zu korrigieren. Dieser Server ersetzt diese Beschreibung durch die einzige Regel, die das Modell tatsächlich benötigt.

Ausführung in Docker mit einem gebundenen Home-Verzeichnis. Wenn Ihr Agent MCP-Server mit HOME startet, das auf ein Bind-Mount zeigt, baut npx seinen Paket-Cache bei jeder Verbindung über dieses Mount neu auf, was Minuten dauern und zu Timeouts führen kann. Installieren Sie stattdessen global im Image und richten Sie command: auf die Binärdatei.

Fehlerbehebung

Überprüfen Sie, dass der Server startet und seine Tools auflistet:

CLICKUP_API_KEY=pk_... CLICKUP_TEAM_ID=... npx -y github:breckenreed/clickup-mcp-full --help

Missing required environment bedeutet, dass die Variablen den Prozess nicht erreicht haben: Die meisten Clients benötigen sie im eigenen env-Block des Servers, nicht in Ihrer Shell.

Ein 401 von einem Tool bedeutet, dass das Token falsch ist oder widerrufen wurde. Ein 429 bedeutet, dass Sie das Ratenlimit erreichen, also erhöhen Sie REQUEST_SPACING.

Lizenz

MIT, wie der Upstream-Server, den es kapselt. @twofeetup/clickup-mcp ist die MIT-lizenzierte Community-Fortsetzung des vorausbezahlten Baums von @taazkareem/clickup-mcp-server.