clickup-mcp

Servidor MCP de ClickUp para Claude: expone tareas, espacios, carpetas, listas y comentarios de ClickUp como herramientas MCP.

Stack tecnológico: Python 3.12 + uv + FastMCP (Starlette/FastAPI)

Inicio rápido

# 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

Configuración

Copia .env.example a .env y completa tus valores:

Obtén tu token de API: ClickUp → Ajustes → Apps → Token de API

Configuración de Claude Desktop

Añade a claude_desktop_config.json:

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

Modos de transporte

stdio (Claude Desktop / CLI)

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

HTTP — monousuario

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

HTTP — gateway / multiusuario

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

Herramientas disponibles (28)

Cómo encontrar el ID de usuario de ClickUp de una persona

Usa clickup_list_members. La respuesta nativa de ClickUp GET /team incluye una lista completa de miembros por equipo (teams[].members[].user.{id,username,email}), pero clickup_get_workspaces elimina eso para mantener su respuesta pequeña, por lo que no es el lugar para buscar personas. clickup_list_members lee el mismo endpoint subyacente y proyecta la lista de miembros a una forma plana y específica (id/username/email/team_id/role) para que los llamadores no tengan que extraerla del objeto completo del espacio de trabajo/equipo. clickup_list_tasks_for_person utiliza la misma búsqueda interna para resolver email -> user_id.

Brecha conocida: el objeto de miembro de equipo de ClickUp no tiene un campo fiable "este miembro está desactivado" — clickup_list_members no devuelve un campo active, ya que nada real lo respaldaría (el único campo status presente en el objeto sin procesar, invited_by.status, describe al invitador, no al miembro).

clickup_search_tasks ya devuelve status.type

Como cualquier otra herramienta de lectura aquí, clickup_search_tasks y clickup_get_task pasan el objeto de tarea sin procesar de ClickUp sin modificar, incluido el campo type del objeto status (open / custom / closed / done), que es la única forma fiable de saber si un estado con nombre personalizado cuenta como completado. No fue necesario ningún cambio de código para esto; ya estaba ahí. clickup_list_tasks_for_person lo muestra explícitamente como status_type en cada tarea devuelta por conveniencia.

Cómo se representan los EOS Rocks en este espacio de trabajo de ClickUp

Confirmado el 18/08/2026 inspeccionando directamente los campos de una tarea rock real (no adivinado): Los Rocks son tareas regulares de ClickUp que viven en una lista literalmente llamada "Rocks" (encontrada bajo Espacio "Company" > Carpeta "EOS Traction"), cada una con campos personalizados dedicados: Quarter (desplegable, "Q1 2024".."Q4 2026"), Rocks Status (En espera / Fuera de camino / En camino / Completado / Bloqueado / En riesgo), Rock Type (Empresa / Individual / Departamental / Rock de equipo), Department, y progreso a través de Progress (manual) o Progress % (automático, resumen de lista de verificación). Esto no es la API de Objetivos de ClickUp ni una lista de tareas simple sin metadatos: son tareas más campos personalizados.

clickup_list_rocks_for_org descubre cada lista llamada "Rocks" (por nombre, no un ID fijo, en caso de que los espacios/carpetas se reorganizen) en todos los espacios de trabajo visibles para el token, lee estos campos y los normaliza:

• quarter: la etiqueta "Q3 2026" de ClickUp se convierte a 2026-Q3 (y viceversa, para el filtro de entrada quarter).

• status: las 6 opciones sin procesar de ClickUp se asignan al contrato de 5 valores (on_track/off_track/done/missed/open) — consulta el comentario _STATUS_MAP en rocks.py para conocer la asignación exacta y por qué missed nunca se emite (nada en los datos de ClickUp distingue "se quedó sin tiempo" de "fuera de camino" genérico; derivarlo de una fecha de vencimiento vencida sería una suposición de lógica empresarial no confirmada, por lo que no se hace aquí).

• measurable: no existe un campo dedicado en esta lista. Se recurre a la descripción de la tarea; null si también está vacía (nunca se fabrica).

• weekly_status: no se encontró ninguna fuente estructurada en ninguna parte (ni un campo personalizado, ni derivado de comentarios) — siempre se devuelve como []. Si la organización comienza a rastrear esto en ClickUp de otra manera, revisar.

Archivos adjuntos e imágenes

La API REST de ClickUp no tiene forma de adjuntar un archivo directamente a un comentario, solo a una tarea (POST /task/{task_id}/attachment, que es lo que envuelve clickup_attach_task_file). Tampoco hay un endpoint para eliminar/actualizar archivos adjuntos; volver a subir añade un nuevo adjunto en lugar de reemplazar el anterior, y eliminar uno requiere la aplicación web/escritorio de ClickUp. Confirmado también revisando las descripciones de herramientas del servidor MCP oficial de ClickUp: la misma división (una herramienta Create Task Comment sin soporte para adjuntos, y una herramienta separada Attach File to Task).

Para que una imagen aparezca en línea dentro de un comentario, el truco subyacente es: subir el archivo a la tarea primero, luego hacer referencia a la URL devuelta desde la respuesta del archivo usando la sintaxis de imagen Markdown en el texto del comentario; el renderizador de comentarios de ClickUp lo muestra como una imagen real, no solo un enlace. clickup_create_comment_with_image realiza ambos pasos en una sola llamada:

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)"

Para hacerlo manualmente (por ejemplo, para añadir otro texto alrededor de la imagen), llama tú mismo a las dos herramientas:

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']})"
   )

Referencia de la API

• Documentación de la API v2 de ClickUp

• Crear adjunto de tarea