ClickUp MCP-Server

Eine Model Context Protocol-Serverimplementierung für die ClickUp-Integration, die es KI-Assistenten ermöglicht, mit ClickUp-Arbeitsbereichen zu interagieren.

Dieser Server wird gemäß der MCP-Spezifikation über Stdio ausgeführt, wenn er von einem MCP-Client aufgerufen wird.

Schnellstart

Dieser Server verwendet Ihr persönliches ClickUp-API-Token zur Authentifizierung.

1. Generieren Sie ein persönliches API-Token: Navigieren Sie in Ihren ClickUp-Einstellungen zu „Meine Einstellungen“ > „Apps“ und generieren Sie ein Token.

2. Konfigurieren Sie Ihren MCP-Client (z. B. Claude für Desktop): Legen Sie die erforderliche Umgebungsvariable fest, wenn Sie den Server für Ihren Client konfigurieren.

Beispielkonfigurationsausschnitt für einen MCP-Client:

3. Starten Sie Ihren MCP-Client neu.

Der Server wird bei Bedarf automatisch vom MCP-Client heruntergeladen und gestartet.

Installation über Smithery

So installieren Sie ClickUp MCP Server für Claude Desktop automatisch über Smithery :

Umgebungsvariablen

Erforderlich

• CLICKUP_PERSONAL_TOKEN : Ihr persönliches ClickUp-API-Token. Dies ist für die Authentifizierung des Servers mit der ClickUp-API erforderlich.

Optional

• LOG_LEVEL : Protokollierungsebene für den Server. Unterstützt error , warn , info und debug . Standardmäßig info .

• ENCRYPTION_KEY : Ein persistenter, 32 Byte langer, hexadezimal kodierter Schlüssel. Das Konfigurationssystem ( src/config/app.config.ts ) lädt oder generiert diesen Schlüssel, und src/security.ts enthält Verschlüsselungs-/Entschlüsselungsfunktionen. Dieser Mechanismus wird derzeit jedoch nicht zur Verschlüsselung des CLICKUP_PERSONAL_TOKEN im Authentifizierungsablauf des persönlichen API-Tokens des ClickUpServiceverwendet .

• PORT : Server-Port. Dieser wird vom Standard-MCP-Servermodus von Stdio nicht verwendet, kann aber relevant sein, wenn ein HTTP-Transport oder zusätzliche HTTP-Funktionen (wie ein separater Integritätsprüfungsendpunkt) explizit hinzugefügt wurden. Der Standardwert in der Konfiguration ist 3000 wenn er gelesen wird.

Verfügbare Tools

Die folgenden MCP-Tools sind derzeit implementiert:

Aufgabenverwaltung

• clickup_create_task : Erstellen Sie eine neue Aufgabe in einer ClickUp-Liste.

  • Erforderlich: list_id , name .

  • Optional: description , status , priority , assignees , due_date , time_estimate , tags .

• clickup_update_task : Aktualisieren Sie die Eigenschaften einer vorhandenen Aufgabe.

  • Erfordert: task_id .

  • Optional: Alle beschreibbaren ClickUpTask Eigenschaften.

Team- und Listenverwaltung

• clickup_get_teams : Ruft alle zugänglichen Teams ab (Arbeitsbereiche in ClickUp API v2).

• clickup_get_lists : Ruft alle Listen in einem bestimmten Ordner ab.

  • Erfordert: folder_id .

Vorstandsmanagement

• clickup_create_board : Erstellen Sie ein neues Board in einem ClickUp-Bereich.

  • Erfordert: space_id , name .

Raummanagement

• clickup_get_spaces : Ruft alle Spaces für einen bestimmten Arbeitsbereich (Team) ab.

  • Erforderlich: team_id (Workspace-ID).

  • Optional: archived (Boolesch, standardmäßig „ false ).

• clickup_create_space : Erstellt einen neuen Bereich innerhalb eines Arbeitsbereichs.

  • Erforderlich: team_id (Arbeitsbereichs-ID), name .

  • Optional: multiple_assignees (Boolesch), features (Objekt mit Feature-Flags wie due_dates , time_tracking usw.).

• clickup_get_space : Ruft Details für einen bestimmten Space ab.

  • Erfordert: space_id .

• clickup_update_space : Aktualisiert einen vorhandenen Space.

  • Erfordert: space_id .

  • Optional: name , color , private , admin_can_manage , archived , features .

• clickup_delete_space : Löscht einen Bereich.

  • Erfordert: space_id .

Ordnerverwaltung

• clickup_get_folders : Ruft alle Ordner innerhalb eines bestimmten Bereichs ab.

  • Erfordert: space_id .

  • Optional: archived (Boolesch, standardmäßig „ false ).

• clickup_create_folder : Erstellt einen neuen Ordner innerhalb eines Space.

  • Erfordert: space_id , name .

• clickup_get_folder : Ruft Details für einen bestimmten Ordner ab.

  • Erfordert: folder_id .

• clickup_update_folder : Aktualisiert einen vorhandenen Ordner.

  • Erfordert: folder_id , name .

• clickup_delete_folder : Löscht einen Ordner.

  • Erfordert: folder_id .

Benutzerdefinierte Feldverwaltung

• clickup_get_custom_fields : Ruft alle zugänglichen benutzerdefinierten Felder für eine bestimmte Liste ab.

  • Erforderlich: list_id .

• clickup_set_task_custom_field_value : Legt den Wert eines benutzerdefinierten Felds für eine bestimmte Aufgabe fest.

  • Erfordert: task_id , field_id , value .

  • Optional: value_options (Objekt, z. B. { "time": true } für Datumsfelder).

• clickup_remove_task_custom_field_value : Entfernt/löscht den Wert eines benutzerdefinierten Felds aus einer bestimmten Aufgabe.

  • Erforderlich: task_id , field_id .

Dokumentenverwaltung

Hinweis: Die ClickUp-API für Dokumente (insbesondere Version 2, wobei einige Vorgänge jetzt Version 3 verwenden) weist Einschränkungen auf. Inhalte werden hauptsächlich als Markdown verarbeitet. Erweiterte Formatierungen oder komplexe Einbettungen werden möglicherweise nicht vollständig unterstützt. Das direkte Löschen von Dokumenten über die API wird derzeit vom ClickUp-V3-/docs-Endpunkt nicht unterstützt. Verwalten Sie den Dokumentenlebenszyklus durch Archivierung oder Seitenbearbeitung.

• clickup_search_docs : Sucht nach Dokumenten innerhalb eines Arbeitsbereichs (Teams).

  • Erfordert: workspace_id .

  • Optional: query (Zeichenfolge), include_archived (Boolesch).

• clickup_create_doc : Erstellt ein neues Dokument.

  • Erforderlich: workspace_id , name .

  • Optional: parent (Objekt mit id und type ), visibility (Zeichenfolge: „privat“, „Arbeitsbereich“, „öffentlich“), create_page (Boolesch).

• clickup_get_doc_pages : Ruft die Liste der Seiten innerhalb eines bestimmten Dokuments ab.

  • Erfordert: doc_id .

• clickup_create_doc_page : Erstellt eine neue Seite innerhalb eines bestimmten Dokuments.

  • Erforderlich: workspace_id , doc_id , name (Seitentitel).

  • Optional: content (Markdown), orderindex (Zahl, obwohl die v3-API diese möglicherweise nicht verwendet), parent_page_id (Zeichenfolge), sub_title (Zeichenfolge), content_format (Zeichenfolge).

• clickup_get_doc_page_content : Ruft den Inhalt (Markdown) einer bestimmten Dokumentseite ab.

  • Erfordert: workspace_id , doc_id , page_id .

  • Optional: content_format (Zeichenfolge).

• clickup_edit_doc_page_content : Aktualisiert den Inhalt und/oder Titel einer bestimmten Dokumentseite.

  • Erfordert: workspace_id , doc_id , page_id , content (Markdown).

  • Optional: title (Zeichenfolge, wird API-Name zugeordnet), sub_title (Zeichenfolge), content_edit_mode (Zeichenfolge: „Ersetzen“, „Anhängen“, „Voranstellen“), content_format (Zeichenfolge).

Ansichtsverwaltung

• clickup_get_views : Ruft alle Ansichten für eine bestimmte übergeordnete Ressource (Team, Bereich, Ordner oder Liste) ab.

  • Erforderlich: parent_id (ID der übergeordneten Ressource), parent_type (Zeichenfolge: „Team“, „Bereich“, „Ordner“ oder „Liste“).

• clickup_create_view : Erstellt eine neue Ansicht innerhalb eines Teams, Bereichs, Ordners oder einer Liste.

  • Erfordert: parent_id , parent_type , name (Zeichenfolge: Name der neuen Ansicht), type (Zeichenfolge: Typ der Ansicht, z. B. „Liste“, „Board“, „Kalender“, „Gantt“).

  • Optional: grouping , divide , sorting , filters , columns , team_sidebar , settings (Objekte, die Ansichtskonfigurationen definieren).

• clickup_get_view_details : Ruft Details für eine bestimmte Ansicht ab.

  • Erfordert: view_id .

• clickup_update_view : Aktualisiert eine vorhandene Ansicht.

  • Erfordert: view_id .

  • Optional: name (Zeichenfolge), grouping , divide , sorting , filters , columns , team_sidebar , settings .

• clickup_delete_view : Löscht eine Ansicht.

  • Erfordert: view_id .

• clickup_get_view_tasks : Ruft Aufgaben ab, die zu einer bestimmten Ansicht gehören.

  • Erfordert: view_id .

  • Optional: page (Nummer: 0-indizierte Seitennummer für die Paginierung).

Entwicklung

1. Klonen Sie das Repository:

   git clone <repository_url> cd clickup-mcp-server

2. Installieren Sie Abhängigkeiten:

   npm install

3. Erstellen Sie eine .env Datei im Stammverzeichnis und fügen Sie Ihr CLICKUP_PERSONAL_TOKEN hinzu:

   CLICKUP_PERSONAL_TOKEN=your_actual_personal_api_token_here LOG_LEVEL=debug

4. Starten Sie im Entwicklungsmodus (Stdio): Der Server wartet auf MCP-Nachrichten auf stdin/stdout.

   npm run dev

   Dies verwendet ts-node-dev um src/index.ts auszuführen.

5. Für die Produktion erstellen:

   npm run build

   Dadurch wird TypeScript in dist/ kompiliert.

6. Führen Sie Tests durch:

   npm test

   Dadurch werden Jest-Unit-Tests ausgeführt, die sich in src/__tests__ befinden. Stellen Sie sicher, dass Sie über eine .env.test Datei verfügen (siehe src/__tests__/setup.ts ).

Testen mit MCP Inspector

Sie können den Server lokal mit dem MCP Inspector testen:

1. Stellen Sie sicher, dass Ihr CLICKUP_PERSONAL_TOKEN verfügbar ist. Sie können entweder:

   • Legen Sie es in Ihrer Shell-Umgebung fest, bevor Sie den Inspector ausführen.

   • Legen Sie es in der MCP Inspector-Benutzeroberfläche fest, wenn diese eine Option für Serverumgebungsvariablen bietet.

   • Haben Sie es in Ihrer lokalen .env Datei (da src/index.ts``dotenv lädt).

2. Führen Sie den Inspector mit dem Server aus:

   npx @modelcontextprotocol/inspector node --loader ts-node/esm src/index.ts

   Die Inspector-Benutzeroberfläche sollte gestartet werden, sodass Sie eine Verbindung zum Server herstellen und seine Tools aufrufen können.

Sicherheit

• Die Authentifizierung erfolgt mit Ihrem persönlichen ClickUp-API-Token. Bewahren Sie dieses Token sicher und vertraulich auf. Behandeln Sie es wie ein Passwort.

• Der Server erwartet, dass das CLICKUP_PERSONAL_TOKEN über eine Umgebungsvariable vom nutzenden MCP-Client oder der Entwicklungsumgebung bereitgestellt wird.

• Das Konfigurationssystem enthält eine Logik für einen ENCRYPTION_KEY und src/security.ts verfügt über Verschlüsselungsfunktionen, die jedoch derzeit vom ClickUpService nicht auf das Personal API Token angewendet werden.

• Standardmäßig werden mit LOG_LEVEL=info keine sensiblen Daten (wie das Token selbst) protokolliert. Auf Debug-Ebene werden möglicherweise mehr Details protokolliert.

• Die Ratenbegrenzung für ClickUp-API-Aufrufe wird durch die Protokollierung der verbleibenden Anfragen gehandhabt (siehe ClickUpService ).

Fehlerbehebung

Häufige Probleme

1. Authentifizierungsfehler (401 von ClickUp API)

   • Überprüfen Sie, ob Ihre Umgebungsvariable CLICKUP_PERSONAL_TOKEN richtig eingestellt ist und vom Serverprozess darauf zugegriffen werden kann.

   • Stellen Sie sicher, dass das Token gültig ist und in Ihren ClickUp-Einstellungen nicht widerrufen wurde.

   • Überprüfen Sie die Serverprotokolle auf Nachrichten von ClickUpService bezüglich der Authentifizierung.

2. Ratenbegrenzung durch ClickUp-API

   • Der Server protokolliert Ratenbegrenzungsinformationen aus ClickUp-API-Antworten.

   • Wenn Ratenbegrenzungen häufig erreicht werden, deutet dies auf eine hohe Auslastung hin. Der Server selbst implementiert keine Warteschlangen oder komplexe Backoffs, die über das hinausgehen, was axios standardmäßig tun könnte.

3. Server startet nicht / Verbindungsprobleme mit MCP Inspector

   • Stellen Sie sicher, dass CLICKUP_PERSONAL_TOKEN festgelegt ist.

   • Wenn Sie npm run dev verwenden, suchen Sie in der Konsole nach TypeScript- oder ts-node-dev Fehlern.

   • Wenn Sie MCP Inspector mit node --loader ts-node/esm src/index.ts verwenden, stellen Sie sicher, dass ts-node und Projektabhängigkeiten korrekt installiert sind.

   • Suchen Sie nach Konsolenfehlern von src/index.ts oder ClickUpService .

Abrufen von Serverprotokollen

• Bei der Ausführung über npm run dev oder npm start werden die Protokolle an die Konsole gesendet.

• Wenn die Anwendung von einem MCP-Client (wie Claude für Desktop) ausgeführt wird, werden die Protokolle in der Regel von diesem Client verwaltet. Für Claude für Desktop finden Sie die Protokolle häufig unter:

  • Windows: %USERPROFILE%\AppData\Local\Claude\Logs\mcp\<server_name_and_id>\<process_id>.log (der Pfad kann leicht abweichen)

  • macOS: ~/Library/Logs/Claude/mcp/<server_name_and_id>\<process_id>.log (Pfad kann leicht abweichen)

Unterstützung

Wenn Sie dieses Projekt hilfreich finden, denken Sie darüber nach, mir einen Kaffee zu spendieren, um die laufende Entwicklung und Wartung zu unterstützen.

Lizenz

MIT-Lizenz – Einzelheiten finden Sie in der Datei „LICENSE“