clickup-mcp

ClickUp MCP-Server für Claude – stellt ClickUp-Aufgaben, Spaces, Ordner, Listen und Kommentare als MCP-Tools bereit.

Technologie-Stack: Python 3.12 + uv + FastMCP (Starlette/FastAPI)

Schnellstart

# Install dependencies
cd D:\leo\mcp-server\clickup-mcp
uv sync

# Run in stdio mode (for Claude Desktop)
$env:CLICKUP_API_TOKEN="pk_xxxxx"
uv run clickup-mcp

Related MCP server: Clickup Universal MCP Server

Konfiguration

Kopieren Sie .env.example nach .env und füllen Sie Ihre Werte ein:

Holen Sie sich Ihren API-Token: ClickUp → Einstellungen → Apps → API-Token

Claude Desktop Einrichtung

Fügen Sie zu claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "clickup": {
      "command": "uv",
      "args": ["run", "--directory", "D:/leo/mcp-server/clickup-mcp", "clickup-mcp"],
      "env": {
        "CLICKUP_API_TOKEN": "pk_xxxxx"
      }
    }
  }
}

Transportmodi

stdio (Claude Desktop / CLI)

$env:CLICKUP_API_TOKEN="pk_xxxxx"
uv run clickup-mcp

HTTP – Einzelmandant

$env:CLICKUP_API_TOKEN="pk_xxxxx"
$env:MCP_TRANSPORT="http"
$env:MCP_HTTP_PORT="8080"
uv run clickup-mcp

HTTP – Gateway / Mehrfachmandant

$env:MCP_TRANSPORT="http"
$env:AUTH_MODE="gateway"
uv run clickup-mcp
# Each request must include: X-Clickup-Token: pk_xxxxx

Verfügbare Tools (28)

Die ClickUp-Benutzer-ID einer Person finden

Verwenden Sie clickup_list_members. Die native GET /team-Antwort von ClickUp enthält eine vollständige Mitgliederliste pro Team (teams[].members[].user.{id,username,email}), aber clickup_get_workspaces entfernt diese, um die Antwort klein zu halten, daher ist es nicht der richtige Ort, um Personen nachzuschlagen. clickup_list_members liest denselben zugrundeliegenden Endpunkt und projiziert die Mitgliederliste in eine flache, zweckgerichtete Form (id/username/email/team_id/role), sodass Aufrufer sie nicht selbst aus dem vollständigen Arbeitsbereichs-/Team-Objekt extrahieren müssen. clickup_list_tasks_for_person verwendet intern dieselbe zugrundeliegende Suche, um email -> user_id aufzulösen.

Bekannte Lücke: Das ClickUp-Teammitglied-Objekt hat kein zuverlässiges Feld "ist dieses Mitglied deaktiviert" – clickup_list_members gibt kein active-Feld zurück, da nichts Reales dahinterstehen würde (das einzige status-Feld, das im Rohobjekt vorhanden ist, invited_by.status, beschreibt den Einladenden, nicht das Mitglied).

clickup_search_tasks gibt bereits status.type zurück

Wie jedes andere Lesetool hier geben clickup_search_tasks und clickup_get_task das rohe ClickUp-Aufgabenobjekt unverändert weiter – einschließlich des type-Felds des status-Objekts (open / custom / closed / done), das die einzige zuverlässige Möglichkeit ist, festzustellen, ob ein benutzerdefinierter Status als erledigt gilt. Dafür war keine Codeänderung erforderlich; es war bereits vorhanden. clickup_list_tasks_for_person zeigt es explizit als status_type auf jeder zurückgegebenen Aufgabe zur Vereinfachung an.

Wie EOS-Rocks in diesem ClickUp-Arbeitsbereich dargestellt werden

Bestätigt am 18.08.2026 durch direkte Inspektion der Felder einer echten Rock-Aufgabe (nicht geraten): Rocks sind normale ClickUp-Aufgaben, die sich in einer Liste mit dem Namen "Rocks" befinden (gefunden unter Space "Company" > Ordner "EOS Traction"), die jeweils dedizierte benutzerdefinierte Felder tragen: Quarter (Dropdown, "Q1 2024".."Q4 2026"), Rocks Status (On Hold / Off Track / On Track / Completed / Blocked / At Risk), Rock Type (Company / Individual / Departmental / Team Rock), Department und Fortschritt entweder über Progress (manuell) oder Progress % (automatisch, Checklisten-Zusammenfassung). Dies ist weder die ClickUp-Goals-API noch eine einfache Aufgabenliste ohne Metadaten – es sind Aufgaben plus benutzerdefinierte Felder.

clickup_list_rocks_for_org findet jede Liste mit dem Namen "Rocks" (anhand des Namens, nicht einer fest codierten ID, falls Spaces/Ordner neu organisiert werden) in jedem für das Token sichtbaren Arbeitsbereich, liest diese Felder und normalisiert sie:

• quarter: ClickUps "Q3 2026"-Label wird in 2026-Q3 umgewandelt (und zurück, für den quarter-Eingabefilter).

• status: ClickUps 6 Rohoptionen werden auf den 5-Werte-Vertrag abgebildet (on_track/off_track/done/missed/open) – siehe den _STATUS_MAP-Kommentar in rocks.py für die genaue Zuordnung und warum missed nie ausgegeben wird (nichts in ClickUps Daten unterscheidet "Zeit abgelaufen" von generischem "off track"; die Ableitung aus einem überfälligen due_date wäre eine unbestätigte Geschäftslogik-Annahme, daher wird dies hier nicht gemacht).

• measurable: kein dediziertes Feld existiert in dieser Liste. Fallback auf die Aufgabenbeschreibung; null, wenn auch diese leer ist (niemals erfunden).

• weekly_status: es wurde keine strukturierte Quelle gefunden (weder ein benutzerdefiniertes Feld noch etwas, das von Kommentaren abgeleitet ist) – wird immer als [] zurückgegeben. Falls die Organisation dies auf andere Weise in ClickUp zu verfolgen beginnt, überprüfen Sie dies erneut.

Anhänge und Bilder

ClickUps REST-API hat keine Möglichkeit, eine Datei direkt an einen Kommentar anzuhängen – nur an eine Aufgabe (POST /task/{task_id}/attachment, was clickup_attach_task_file kapselt). Es gibt auch keinen Endpunkt zum Löschen/Aktualisieren von Anhängen; erneutes Hochladen fügt einen neuen Anhang hinzu, anstatt den alten zu ersetzen, und das Entfernen eines Anhangs erfordert die ClickUp-Web-/Desktop-App. Bestätigt durch Überprüfung der Tool-Beschreibungen des offiziellen ClickUp-MCP-Servers – derselbe Split (ein Create Task Comment-Tool ohne Anhangsunterstützung und ein separates Attach File to Task-Tool).

Damit ein Bild inline in einem Kommentar angezeigt wird, ist der zugrundeliegende Trick: Laden Sie die Datei zuerst zur Aufgabe hoch und verweisen Sie dann auf die zurückgegebene URL aus der Dateiantwort mit der Markdown-Bildsyntax im Kommentartext – ClickUps Kommentar-Renderer zeigt es als echtes Bild inline an, nicht nur als Link. clickup_create_comment_with_image führt beide Schritte in einem Aufruf aus:

clickup_create_comment_with_image(task_id, file_content_base64, filename)
# internally:
#   1. POST /task/{task_id}/attachment  -> {"url": "...", ...}
#   2. POST /task/{task_id}/comment     comment_text = "![filename](url)"

Um es stattdessen manuell zu tun (z. B. um anderen Text um das Bild herum hinzuzufügen), rufen Sie die beiden Tools selbst auf:

1. result = clickup_attach_task_file(task_id, file_content_base64, filename)
   -> result["url"] is the uploaded file's URL

2. clickup_create_task_comment(
     task_id,
     comment_text=f"![{filename}]({result['url']})"
   )

API-Referenz

• ClickUp API v2 Dokumentation

• Aufgabenanhang erstellen