ClickUp MCP Server

Ein Model Context Protocol Server für ClickUp, aufgebaut auf zwei Ideen:

Alles trägt menschliche Namen. find(scope: "Cavalry/Findings", assignee: "me", due: "overdue") — keine IDs, kein Durchlaufen des Baums, um sie zu entdecken. Namen, die sich nicht auflösen lassen, erzeugen einen Fehler, der die gültigen Optionen auflistet, denn ein selbstbewusst leeres Ergebnis ist schlimmer als ein Fehlschlag.

Du entscheidest, was er kann. Vier Fähigkeitsprofile, durchgesetzt bei jeder ausgehenden Anfrage. Gib einem unbeaufsichtigten Agenten das Profil agent und er kann Aufgaben und Kommentare erstellen, aber nichts Bestehendes ändern oder löschen.

18 Werkzeuge, 354 Tests. Version 4.3.0 — siehe CHANGELOG.md. Ein stark renovierter Fork von nsxdavid/clickup-mcp-server.

Status: 4.x ist neu. Es hat fünf adversariale Red-Team-Runden durchlaufen, wurde aber noch nicht in Produktion eingesetzt. Die vorherige 3.x-Linie wird weiterhin in diesem Repository ausgeliefert und ist weiterhin das, was die Referenzbereitstellung ausführt — siehe Ausführen von 3.x.

Schnellstart

Hole dir ein Token von ClickUp → Einstellungen → Apps → API-Token (es beginnt mit pk_). Der Workspace wird automatisch erkannt — es gibt nichts weiter zu konfigurieren.

Ohne Installation:

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["-y", "github:benthesoundguy/clickup-mcp-server"],
      "env": { "CLICKUP_API_TOKEN": "pk_your_token_here" }
    }
  }
}

Oder aus einem Klon, was du willst, wenn du etwas ändern möchtest:

git clone https://github.com/benthesoundguy/clickup-mcp-server
cd clickup-mcp-server
npm install          # builds automatically
npm run check        # verifies the token and connects — do this before wiring up a client

{
  "mcpServers": {
    "clickup": {
      "command": "node",
      "args": ["/absolute/path/to/clickup-mcp-server/build/v4/index.js"],
      "env": { "CLICKUP_API_TOKEN": "pk_your_token_here" }
    }
  }
}

Wo dieser Block hingehört

Die obige Form funktioniert unverändert in Claude Desktop, Claude Code, Cursor, Cline und Windsurf — sie alle verwenden den Schlüssel mcpServers. Zwei Clients unterscheiden sich:

• VS Code (.vscode/mcp.json) verwendet servers statt mcpServers. Gleiche innere Form. Das Kopieren einer Cursor-Konfiguration unverändert ist der häufigste Einrichtungsfehler.

• Zed (settings.json) verwendet context_servers und verschachtelt den Befehl:

  { "context_servers": { "clickup": { "command": { "path": "node", "args": ["/path/to/build/v4/index.js"] } } } }

Claude Code kann die Datei ganz überspringen:

claude mcp add clickup --env CLICKUP_API_TOKEN=pk_... -- npx -y github:benthesoundguy/clickup-mcp-server

Das Token stattdessen in eine Datei legen

Wenn du ein Token nicht in eine Client-Konfiguration einfügen möchtest — Desktop-Apps überschreiben diese Dateien und können eine veraltete Kopie beibehalten — lege es in eine .env neben der Installation und lasse den env-Block ganz weg:

echo 'CLICKUP_API_TOKEN=pk_your_token_here' > .env

Der Server sucht in <cwd>/.env, <install>/.env und <install>/../.env, in dieser Reihenfolge, und sagt beim Start, welche er verwendet hat. Das Token aus der Datei hat Vorrang vor der Umgebung, sodass das Rotieren an einer Stelle tatsächlich wirksam wird. Jede andere Einstellung funktioniert umgekehrt — ein expliziter Wert in deiner Client-Konfiguration gewinnt immer, sodass eine verirrte .env niemals MCP_PROFILE erweitern kann. Setze MCP_STRICT_ENV=1 auf einem Server, um die gesamte Suche abzuschalten.

Wenn es nicht funktioniert

npm run check          # from a clone
node build/v4/index.js --check

Dies gibt jede Eingabe aus, die der Server aufgelöst hat — welche .env er gefunden hat und was er angewendet hat, ob das Token vorhanden und in der richtigen Form ist, das aktive Profil und die Werkzeuganzahl, die Node-Version und den Build-Stempel — und verbindet sich dann tatsächlich mit ClickUp und meldet, wer du bist und dein Ratenbudget. Es gibt niemals das Token aus, sodass die Ausgabe sicher in ein Issue eingefügt werden kann.

Wenn das Token fehlt, stirbt der Server nicht still im stdio-Modus. Er startet, registriert seine Werkzeuge, und jeder Aufruf antwortet mit dem, was falsch ist und wie man es behebt, sodass das Problem in deinem Gespräch auftaucht und nicht in einer Logdatei, die du erst suchen musst. (Im HTTP-Modus beendet er sich weiterhin mit 1 — eine unbeaufsichtigte Bereitstellung sollte laut scheitern.)

Related MCP server: ClickUp MCP Server

Fähigkeitsprofile

Ein Binär, vier Profile, ausgewählt mit MCP_PROFILE. Installiere einmal und füge einen Client-Eintrag pro Profil hinzu, um zu ermöglichen, was ein bestimmter Agent haben soll.

Schema-Kosten sind das, was die Werkzeugdefinitionen im Kontext des Modells bei jeder Anfrage verbrauchen, bevor irgendeine Arbeit passiert. Zum Vergleich: 3.x kostet ~18.600 Tokens für 88 Werkzeuge.

agent ist das Interessante. Er kann hinzufügen, aber niemals ändern oder zerstören, sodass das Schlimmste, was ein unbeaufsichtigter Agent tun kann, darin besteht, Unordnung zu erzeugen, die du löschen kannst. Diese Garantie wird in drei Schichten durchgesetzt, und nur die dritte ist eine Sicherheitsgrenze:

1. Werkzeugfilterung — welche Werkzeuge überhaupt erscheinen (Kontextkosten + Werkzeugauswahl)

2. Aktionsfilterung — welche Aktionen ein Werkzeug bewirbt (Kontextkosten + Ehrlichkeit)

3. Schreibrichtlinie — eine Whitelist, die bei jeder ausgehenden Anfrage geprüft wird, einschließlich Uploads ← die Garantie

Schichten 1 und 2 hängen davon ab, dass jedes Werkzeug von jedem zukünftigen Mitwirkenden korrekt getaggt wird. Schicht 3 nicht: Sie inspiziert die tatsächliche Anfrage auf dem Weg nach draußen, sodass ein falsch getaggtes Werkzeug, ein Refactoring oder ein nächstes Jahr hinzugefügter Endpunkt ein Profil nicht erweitern kann. Die Testsuite beweist dies, indem sie core-nur-Handler direkt mit einem agent-Kontext aufruft — wobei Schichten 1 und 2 vollständig umgangen werden — und behauptet, dass nichts auf die Leitung gelangt.

Dinge, die additiv aussehen, aber absichtlich von agent ausgeschlossen sind: Das Anhängen eines Tags, das Setzen eines benutzerdefinierten Felds und das Hinzufügen einer Abhängigkeit mutieren alle eine bestehende Aufgabe; das Erstellen eines Webhooks beginnt, deine Daten an einen externen Endpunkt zu streamen. Nur-Anhängen und sicher sind nicht dieselbe Eigenschaft.

Warum der Standard core und nicht full ist

full gewährt Mitgliedschaftsverwaltung — das Einladen eines Benutzers verbraucht einen kostenpflichtigen Sitzplatz, das Entfernen eines Benutzers ändert den Zugriff einer echten Person — plus Webhooks, die Workspace-Daten an einen externen Ort senden. Nichts davon ist das, wofür eine erste Verbindung gedacht ist, und ein Standard, den niemand ändert, muss der sichere sein. Fordere Verwaltung namentlich an, wenn du sie willst; bis dahin sagt dir die Ablehnung genau, wie.

Anhänge und das Dateisystem

attach liest eine Datei von der Maschine, auf der der Server läuft. Das ist eine Ressource, die die Schreibrichtlinie nicht sehen kann — sie inspiziert URLs, und ein Dateilesen hat keine URL — daher wird sie separat durch CLICKUP_ATTACH_ROOT geregelt:

• Gesetzt → Lesezugriffe sind auf dieses Verzeichnis beschränkt. Die Eindämmung wird gegen den echten Pfad der Datei geprüft, nach Auflösung von .. und jedem Symlink.

• Nicht gesetzt → core und full können jede Datei lesen, die der Prozess kann. Unter agent wird attach überhaupt nicht angeboten (12 Werkzeuge statt 13), weil es keinen sicheren Standard-Root gibt: Das Arbeitsverzeichnis ist normalerweise das Projektverzeichnis, in dem .env liegt.

Ein falsch konfigurierter Root ist beim Start fatal, nicht ignoriert — eine Grenze, die still nicht da ist, ist schlimmer als keine.

Werkzeuge

Werkzeuge verengen sich, wo es sinnvoll ist, statt zu verschwinden: Unter read zeigt comment nur seine Lese-Argumente und checklist bewirbt nur list, sodass das Schema die Wahrheit darüber sagt, was diese Verbindung kann, statt Aktionen zu bewerben, die abgelehnt würden.

Die Regel, der alles folgt

Gib niemals eine selbstbewusste falsche Antwort zurück. ClickUp macht es leicht, das falsch zu machen, weil es auf schlechte Eingaben mit fröhlichem Unsinn antwortet:

Also löst dieser Server Namen auf und erhebt bei Mehrdeutigkeit („Findings", das vier Listen entspricht, ist ein Fehler, der alle vier nennt, nie ein Münzwurf); erhebt statt leer zurückzugeben, wenn ein Filterwert sich nicht auflöst; validiert Enums clientseitig gegen das, was die Liste tatsächlich akzeptiert; verifiziert Schreibvorgänge, denen er nicht vertrauen kann, indem er das Objekt zurückliest; und übertreibt niemals eine Anzahl — eine Abfrage, die das Paging stoppt, meldet 100+ Treffer, und jeder clientseitige Filter meldet, wie viel tatsächlich gescannt wurde.

Fehler sagen, was fehlgeschlagen ist, warum und was als Nächstes zu tun ist, mit den gültigen Optionen aufgelistet.

Umgebungsvariablen

Remote-Modus (Claude Web + Mobile und jeder HTTP-Client)

Der Server spricht streamable HTTP und akzeptiert drei unabhängige Anmeldeinformationen. Jede dieser Anmeldeinformationen authentifiziert eine Anfrage; sie sollen koexistieren, weil verschiedene Clients unterschiedliche Dinge präsentieren können.

MCP_TRANSPORT=http MCP_AUTH_TOKEN=$(openssl rand -hex 24) \
MCP_PROFILE=core CLICKUP_API_TOKEN=... node build/v4/index.js

GET /health ist eine nicht authentifizierte Sonde, die Version, aktives Profil, Tool-Anzahl und Attachment-Stammverzeichnis meldet.

OAuth (was gehostete Clients wollen)

Dieser Server muss kein OAuth-Anbieter sein und ist auch keiner. Seit der MCP-Spezifikation vom 2025-06-18 ist ein MCP-Server ein Ressourcenserver: Er benennt den Autorisierungsserver, dem er vertraut, und validiert die Tokens, die dieser Server ausstellt. Login, Einwilligung und Token-Ausstellung gehören zu Ihrem IdP – Cloudflare Access, WorkOS, Auth0, Descope, Stytch, Keycloak, alles mit OIDC-Discovery.

MCP_TRANSPORT=http \
MCP_PUBLIC_URL=https://mcp.example.com \
MCP_OAUTH_ISSUER=https://your-idp.example.com \
CLICKUP_API_TOKEN=pk_... node build/v4/index.js

Das ist die gesamte Konfiguration. Der Server:

• stellt RFC 9728 Protected Resource Metadata unter /.well-known/oauth-protected-resource bereit, die Ihren Issuer benennt, ohne Authentifizierung;

• beantwortet eine nicht authentifizierte Anfrage mit 401 und einem WWW-Authenticate-Header, der auf dieses Dokument verweist – so findet ein Client heraus, wo er sich anmelden muss;

• entdeckt die Signaturschlüssel Ihres Issuers über /.well-known/openid-configuration (oder RFC 8414) oder verwendet MCP_OAUTH_JWKS_URL, falls Sie ihn setzen;

• validiert jedes Token: RS256 festgeschrieben, Signatur gegen die JWKS des Issuers, exp, nbf, iss und aud – das Token muss diesen Server nennen.

Die letzte Prüfung ist die entscheidende. Ohne sie könnte ein Token, das Ihr IdP für einen anderen Dienst ausgestellt hat, hier wiederverwendet werden. Deshalb ist MCP_PUBLIC_URL erforderlich und wird nicht abgeleitet: Die erwartete Audience darf niemals aus der Anfrage stammen, da der Host-Header vom Aufrufer gesetzt wird.

MCP_AUTH_TOKEN wird optional, sobald ein Issuer konfiguriert ist – eine reine OAuth-Bereitstellung braucht kein gemeinsames Passwort, das sie nie verwendet.

Hinweis zur dynamischen Client-Registrierung. Die Spezifikation vom 2026-07-28 hat DCR zugunsten von Client-ID-Metadaten-Dokumenten als veraltet eingestuft. Diese Änderung betrifft Autorisierungsserver und Clients; ein Ressourcenserver ist in beiden Fällen nicht betroffen, was ein guter Grund ist, zu delegieren, statt einen eigenen AS zu entwickeln.

Die Einschränkung des claude.ai-Connectors

Die benutzerdefinierte Connector-Oberfläche von Claude akzeptiert nur OAuth-Felder – Authorization URL, Token URL, Client ID, Client Secret. Es gibt kein Feld für ein statisches Bearer-Token oder einen benutzerdefinierten Header (#112, #411). Daher:

• Mit konfiguriertem OAuth verbinden Sie ihn als normalen benutzerdefinierten Connector. Das ist der vorgesehene Weg.

• Ohne OAuth ist der einzige Weg die Token-in-URL-Form, /mcp/<token>, aktiviert mit MCP_ALLOW_TOKEN_IN_PATH=1. Sie funktioniert, legt aber eine Anmeldeinformation in eine URL, wo Proxys sie protokollieren; deshalb verweigert der strikte Modus sie. Behandeln Sie sie als Notbehelf, nicht als Bereitstellung.

Cloudflare Access (optionaler dritter Authentifizierungsmodus)

Setzen Sie CF_ACCESS_TEAM_DOMAIN und CF_ACCESS_AUD, und der Server validiert den Cf-Access-Jwt-Assertion-Header, den Access jeder weitergeleiteten Anfrage hinzufügt: RS256 gegen die Team-JWKS, plus exp, iss und aud. Beide Access-Flows validieren über einen Pfad – eine Browser-Anmeldung enthält email, ein Service-Token enthält common_name.

Das ist Verteidigung in der Tiefe. Eine Anfrage, die den Origin ohne Durchlauf durch Access erreicht – eine Tunnel-Fehlkonfiguration, ein zweiter Ingress, etwas im Netzwerk des Hosts – kann keinen Access-authentifizierten Aufrufer imitieren. Im Fehlerfall verweigert sie den Zugriff: alg ist auf RS256 festgelegt (sodass alg: none und HS256-Algorithmus-Verwechslung abgelehnt werden), eine nicht erreichbare JWKS führt zur Verweigerung, nicht zur Umgehung, und die JWKS-URL stammt aus der Konfiguration, nie aus dem Token.

Bearer-Authentifizierung funktioniert weiterhin. Eine Anfrage wird durch ein gültiges Access-JWT oder ein gültiges Bearer-Token autorisiert, daher müssen Agents, die Header unterstützen, nichts ändern.

Der Origin stellt /.well-known/oauth-* nicht bereit – bei aktiviertem Managed OAuth ist Access der Autorisierungsserver und stellt Discovery am Edge bereit.

Strikter Modus (MCP_STRICT_ENV=1)

Die Haltung für eine unbeaufsichtigte Bereitstellung. Geheimnisse müssen aus der Umgebung kommen, der Server erfindet oder persistiert niemals eine Anmeldeinformation, und er beendet sich mit dem Exit-Code 1 und einer umsetzbaren Meldung, statt fehlkonfiguriert zu starten. Er verweigert außerdem die URL-Pfad-Token-Form, die die Anmeldeinformation in Proxy-Zugriffsprotokolle bringt.

Das ist wichtig, weil die Suche nach der .env-Datei bewusst Vorrang vor process.env hat – ein Desktop-Host überschreibt beim Beenden seine eigene Konfigurationsdatei aus dem Speicher, daher muss die Datei dort gewinnen. Auf einem Server ist diese Rangfolge umgekehrt: Eine verirrte .env im Arbeitsverzeichnis würde stillschweigend Vorrang vor der systemd-Unit haben. Der strikte Modus deaktiviert die Suche.

Siehe deploy/DEPLOY.md für das vollständige Rezept: VPS-Setup-Skript, gehärtete systemd-Unit, Cloudflare Tunnel und das Verbinden mit Claude.

Upgrade von 3.x

Die Tool-Namen sind völlig anders – 4.x ist eine Neuimplementierung, keine Umbenennung. Alles, was hartkodierte 3.x-Tool-Namen enthält (gespeicherte Prompts, Agent-Anweisungen, Skripte), muss aktualisiert werden.

Die Zuordnung ist größtenteils viele-zu-eins:

Nicht übernommen: project_intelligence (die acht lokalen Analyseberichte) und reminders_create. Status-Verwaltung – Erstellen, Umbenennen, Neuanordnen von Status – fehlt ebenfalls; meta liest Status, ändert sie aber nicht. Wenn Sie eines davon benötigen, verwenden Sie 3.x.

3.x ausführen

3.x wird weiterhin aus diesem Repository erstellt und ausgeliefert:

npm run start:v3       # via the package script
node build/index.js    # the 3.x entry point directly

Richten Sie einen MCP-Client auf build/index.js statt auf build/v4/index.js, um es weiter zu verwenden.

Die Referenz-systemd-Unit in deploy/ ist bewusst weiterhin auf 3.x festgelegt, weil ein laufender Dienst nicht die Hauptversion wechseln sollte, nur weil sich ein Paketstandard darunter verschoben hat. Migrieren Sie sie, indem Sie ExecStart auf build/v4/index.js zeigen lassen und MCP_PROFILE explizit setzen.

Bekannte Einschränkungen der ClickUp-API

Keine Bugs hier – die API hat diese Funktionen schlicht nicht, und dieser Server meldet die Einschränkung, anstatt sie zu vertuschen.

• Aufgaben können nicht zwischen Listen verschoben werden. POST /list/{dest}/task/{id} gibt 200 {} zurück und tut nichts ohne die ClickApp „Tasks in Multiple Lists“; PUT mit list_id wird stillschweigend ignoriert; /move liefert 404. Der Move-Pfad von update liest die Aufgabe erneut und schlägt laut fehl, anstatt einen nicht erfolgten Move zu melden.

• Anhänge haben keinen Listen-Endpunkt – task liest sie vom Aufgabenobjekt. Uploads sind nur als Multipart möglich und auf 25 MB begrenzt.

• Dokumente können nicht umbenannt oder gelöscht werden, und Seiten können nicht gelöscht werden.

• Definitionen benutzerdefinierter Felder können aufgelistet und erstellt, aber nicht bearbeitet oder gelöscht werden.

• Datumsbezogene benutzerdefinierte Felder erfordern Unix-Millisekunden; YYYY-MM-DD wird von ClickUp für diese abgelehnt. due_date/start_date von Aufgaben akzeptieren beides und werden hier konvertiert.

• Status- und Tag-Namen werden kleingeschrieben gespeichert; der Abgleich hier ist durchgängig case-insensitiv.

• Listen überschreiben ständig die Status ihres Spaces, daher ist „welche Status gültig sind“ eine Frage pro Liste. meta beantwortet sie pro Liste.

• ClickUp antwortet auf ein ungültiges Enum mit HTTP 500, daher werden Enums clientseitig validiert, bevor sie gesendet werden.

• Das Ratelimit liegt bei ungefähr 100 Anfragen/Minute pro Token, geteilt über alles, was es verwendet. whoami meldet das aktuelle Budget; der Server passt sich selbst an die x-ratelimit-*-Header an.

Webhook-Empfänger (optional)

Verarbeitet ClickUp-Webhook-Ereignisse ohne externe Infrastruktur:

WEBHOOK_PORT=3001 WEBHOOK_SECRET=your_secret node build/webhook-receiver/index.js

• HMAC-SHA256-Validierung über den rohen Request-Body; wenn ein Secret konfiguriert ist, werden unsignierte Anfragen abgelehnt

• Strukturierte Ereignisanalyse – Typ, Objekt, Operation, Änderungen, Benutzer, Zeitstempel

• Optionale Weiterleitung an eine Callback-URL (WEBHOOK_FORWARD_URL)

• Reines Node.js http, null zusätzliche Abhängigkeiten

Entwicklung

npm install
npm run build
npm test          # 354 tests, mocked HTTP — no token needed
npm run smoke     # live CRUD walk (needs CLICKUP_API_TOKEN; creates and
                  # deletes its own sandbox in your workspace)

Architekturnotizen für 4.x befinden sich in src/v4/README.md; die Designbegründung und Messungen sind in V4-PLAN.md.

Debuggen eines Fixes, der „nicht funktioniert hat“

Rufen Sie whoami auf. Es meldet die Version und den Stempel des laufenden Builds. MCP-Hosts starten ihren eigenen Serverprozess zu Sitzungsbeginn und halten ihn, daher erreicht ein Rebuild eine bereits laufende Sitzung nicht – wenn der Stempel älter als Ihre Änderung ist, starten Sie die Host-App neu. Dies war für mehrere Phantom-Bugmeldungen verantwortlich, bevor das Tool existierte.

Lizenz

MIT – siehe LICENSE. Fork von nsxdavid/clickup-mcp-server von David Whatley.