ClickUp

clickup-mcp-server: Un servidor MCP de ClickUp

Resumen

Un servidor de Protocolo de Contexto de Modelo (MCP) para la interacción y automatización de la API de ClickUp. Este servidor proporciona herramientas para que los sistemas de IA lean, creen y actualicen tareas, listas y espacios en ClickUp.

Este servidor MCP permite que herramientas de IA como Claude interactúen con tu espacio de trabajo de ClickUp, ayudando a automatizar la gestión de tareas, la planificación de proyectos y otros flujos de trabajo.

Características

Este servidor MCP proporciona una integración completa con ClickUp, ofreciendo las siguientes capacidades:

Gestión de Tareas

• Crear, actualizar y eliminar tareas
• Mover y duplicar tareas entre listas y tableros
• Establecer propiedades de tareas, incluyendo fechas de vencimiento, prioridades y etiquetas
• Crear, ver y gestionar subtareas
• Añadir comentarios y archivos adjuntos a las tareas
• Soporte para operaciones de tareas individuales y masivas
• Agrupación y filtrado de tareas por estado

Organización del Espacio de Trabajo

• Navegar y gestionar espacios de trabajo, espacios, carpetas y listas
• Crear, actualizar y eliminar espacios y carpetas
• Organizar listas dentro de espacios y carpetas
• Ver la jerarquía completa del espacio de trabajo
• Navegar eficientemente por el espacio de trabajo usando notación de ruta
• Crear listas en espacios o dentro de carpetas

Formato y Visualización

• Soporte completo de markdown para descripciones de tareas y comentarios
• Conversión a HTML para una representación adecuada en ClickUp
• Visualización formateada de detalles de tareas, listas y jerarquías
• Visualización mejorada de estructuras de proyectos complejas

Experiencia del Desarrollador

• Manejo integral de errores y validación
• Respuestas de API claras y consistentes
• Documentación detallada para todas las herramientas
• Integración fácil con Claude y otros sistemas de IA

Herramientas

El servidor proporciona las siguientes herramientas para interactuar con ClickUp:

Herramientas de Espacio de Trabajo/Equipo

1. get_workspaces

   • Obtiene todos los espacios de trabajo/equipos
   • Entrada: Ninguna
   • Devuelve: Lista de espacios de trabajo con IDs y nombres

2. navigate_workspace

   • Navega por la jerarquía del espacio de trabajo usando notación de ruta
   • Entrada:
     • path (cadena): Ruta a través de la jerarquía del espacio de trabajo (team_id/space_name/folder_name/list_name)
   • Devuelve: Detalles de la entidad objetivo y su ruta completa

Herramientas de Espacios

3. get_spaces

   • Obtiene todos los espacios en un espacio de trabajo
   • Entrada:
     • workspace_id (cadena): ID del espacio de trabajo/equipo
   • Devuelve: Lista de espacios con IDs y nombres

4. create_space

   • Crea un nuevo espacio en un espacio de trabajo
   • Entradas:
     • workspace_id (cadena): ID del espacio de trabajo/equipo
     • name (cadena): Nombre del nuevo espacio
   • Devuelve: Detalles del espacio creado

5. get_space_hierarchy

   • Obtiene la jerarquía completa de un espacio, incluyendo carpetas y listas
   • Entrada:
     • space_id (cadena): ID del espacio
   • Devuelve: Estructura jerárquica completa del espacio

Herramientas de Carpetas

6. get_folders

   • Obtiene todas las carpetas en un espacio
   • Entrada:
     • space_id (cadena): ID del espacio
   • Devuelve: Lista de carpetas con IDs y nombres

7. create_folder

   • Crea una nueva carpeta en un espacio
   • Entradas:
     • space_id (cadena): ID del espacio
     • name (cadena): Nombre de la nueva carpeta
   • Devuelve: Detalles de la carpeta creada

8. update_folder

   • Actualiza el nombre de una carpeta
   • Entradas:
     • folder_id (cadena): ID de la carpeta a actualizar
     • name (cadena): Nuevo nombre para la carpeta
   • Devuelve: Detalles de la carpeta actualizada

9. delete_folder

   • Elimina una carpeta
   • Entrada:
     • folder_id (cadena): ID de la carpeta a eliminar
   • Devuelve: Confirmación de la eliminación

Herramientas de Listas/Tableros

10. get_lists

    • Obtiene todas las listas/tableros en un espacio
    • Entrada:
      • space_id (cadena): ID del espacio
    • Devuelve: Lista de listas/tableros con IDs y nombres

11. create_list

    • Crea una nueva lista/tablero en un espacio o carpeta
    • Entradas:
      • space_id (cadena): ID del espacio
      • name (cadena): Nombre de la nueva lista/tablero
      • folder_id (cadena, opcional): ID de la carpeta (si se crea la lista en una carpeta)
    • Devuelve: Detalles de la lista/tablero creada

12. organize_lists

    • Organiza listas por su ubicación (en el espacio o en carpetas)
    • Entradas:
      • space_id (cadena): ID del espacio
      • folder_id (cadena, opcional): ID de una carpeta específica
    • Devuelve: Listas organizadas por su carpeta contenedora

Herramientas de Tareas

13. get_tasks

• Obtiene todas las tareas en una lista/tablero
• Entrada:
  • list_id (cadena): ID de la lista/tablero
• Devuelve: Lista de tareas con IDs, nombres y otros detalles

14. get_tasks_by_status

    • Obtiene tareas con un estado específico en una lista/tablero
    • Entradas:
      • list_id (cadena): ID de la lista/tablero
      • status (cadena): Estado para filtrar las tareas
    • Devuelve: Lista de tareas con el estado especificado

15. create_task

    • Crea una nueva tarea en una lista/tablero
    • Entradas:
      • list_id (cadena): ID de la lista/tablero
      • name (cadena): Nombre de la tarea
      • description (cadena, opcional): Descripción de la tarea
      • priority (número, opcional): Prioridad de la tarea (1-4)
      • due_date (número, opcional): Fecha de vencimiento de la tarea en milisegundos
      • tags (cadena[], opcional): Lista de nombres de etiquetas para añadir a la tarea
    • Devuelve: Detalles de la tarea creada

16. get_task

    • Obtiene detalles de una tarea específica
    • Entrada:
      • task_id (cadena): ID de la tarea
    • Devuelve: Detalles completos de la tarea, incluyendo descripción, estado, etc.

17. update_task

    • Actualiza las propiedades de una tarea
    • Entradas:
      • task_id (cadena): ID de la tarea
      • name (cadena, opcional): Nuevo nombre de la tarea
      • description (cadena, opcional): Nueva descripción de la tarea
      • priority (número, opcional): Nueva prioridad de la tarea (1-4)
      • due_date (número, opcional): Nueva fecha de vencimiento en milisegundos
      • tags (cadena[], opcional): Nueva lista de nombres de etiquetas
    • Devuelve: Detalles de la tarea actualizada

18. update_task_status

    • Actualiza el estado de una tarea
    • Entradas:
      • task_id (cadena): ID de la tarea
      • status (cadena): Nuevo estado para la tarea
    • Devuelve: Detalles de la tarea actualizada

19. assign_task

    • Asigna usuarios a una tarea
    • Entradas:
      • task_id (cadena): ID de la tarea
      • assignee_ids (cadena[]): Lista de IDs de usuarios para asignar a la tarea
    • Devuelve: Confirmación de la asignación

20. get_task_subtasks

    • Obtiene subtareas de una tarea
    • Entrada:
      • task_id (cadena): ID de la tarea
    • Devuelve: Lista de subtareas con sus detalles

21. delete_task

    • Elimina una tarea
    • Entrada:
      • task_id (cadena): ID de la tarea a eliminar
    • Devuelve: Confirmación de la eliminación

22. move_task

    • Mueve una tarea a una lista/tablero diferente
    • Entradas:
      • task_id (cadena): ID de la tarea a mover
      • list_id (cadena): ID de la lista/tablero de destino
    • Devuelve: Detalles de la tarea actualizada

23. duplicate_task

    • Duplica una tarea, opcionalmente a una lista/tablero diferente
    • Entradas:
      • task_id (cadena): ID de la tarea a duplicar
      • list_id (cadena, opcional): ID de la lista/tablero de destino
    • Devuelve: Detalles de la tarea duplicada

24. create_subtask

    • Crea una subtarea para una tarea principal
    • Entradas:
      • parent_task_id (cadena): ID de la tarea principal
      • name (cadena): Nombre de la subtarea
      • description (cadena, opcional): Descripción de la subtarea
      • priority (número, opcional): Prioridad de la subtarea (1-4)
      • due_date (número, opcional): Fecha de vencimiento de la subtarea en milisegundos
      • tags (cadena[], opcional): Lista de nombres de etiquetas para la subtarea
    • Devuelve: Detalles de la subtarea creada

25. add_comment

    • Añade un comentario a una tarea
    • Entradas:
      • task_id (cadena): ID de la tarea
      • comment_text (cadena): Contenido de texto del comentario
    • Devuelve: Detalles del comentario añadido

26. add_attachment

    • Añade un archivo adjunto a una tarea mediante URL
    • Entradas:
      • task_id (cadena): ID de la tarea
      • attachment_url (cadena): URL del archivo adjunto a añadir
    • Devuelve: Detalles del archivo adjunto añadido

27. bulk_update_tasks

    • Actualiza múltiples tareas en una lista a la vez
    • Entradas:
      • list_id (cadena): ID de la lista/tablero que contiene las tareas
      • task_ids (cadena[]): Lista de IDs de tareas a actualizar
      • name (cadena, opcional): Nuevo nombre de tarea para todas las tareas
      • description (cadena, opcional): Nueva descripción de tarea para todas las tareas
      • status (cadena, opcional): Nuevo estado para todas las tareas
      • priority (número, opcional): Nueva prioridad para todas las tareas (1-4)
      • due_date (número, opcional): Nueva fecha de vencimiento para todas las tareas en milisegundos
      • tags (cadena[], opcional): Nueva lista de nombres de etiquetas para todas las tareas
    • Devuelve: Confirmación de la actualización masiva

28. bulk_delete_tasks

    • Elimina múltiples tareas a la vez
    • Entrada:
      • task_ids (cadena[]): Lista de IDs de tareas a eliminar
    • Devuelve: Confirmación de la eliminación masiva

Herramientas de Campos Personalizados

29. get_custom_fields

    • Obtiene todos los campos personalizados de una lista/tablero
    • Entrada:
      • list_id (cadena): ID de la lista/tablero
    • Devuelve: Lista de campos personalizados con sus IDs, nombres, tipos y configuración

30. set_custom_field_value

    • Establece un valor de campo personalizado para una tarea usando el ID del campo
    • Entradas:
      • task_id (cadena): ID de la tarea
      • field_id (cadena): ID del campo personalizado
      • value (cualquiera): Valor a establecer para el campo personalizado
    • Devuelve: Confirmación de la actualización del campo personalizado

31. set_custom_field_value_by_name

    • Establece un valor de campo personalizado para una tarea usando el nombre del campo
    • Entradas:
      • task_id (cadena): ID de la tarea
      • list_id (cadena): ID de la lista (necesario para encontrar el campo personalizado por nombre)
      • field_name (cadena): Nombre del campo personalizado
      • value (cualquiera): Valor a establecer para el campo personalizado
    • Devuelve: Confirmación de la actualización del campo personalizado

32. remove_custom_field_value

    • Elimina un valor de campo personalizado de una tarea
    • Entradas:
      • task_id (cadena): ID de la tarea
      • field_id (cadena): ID del campo personalizado
    • Devuelve: Confirmación de la eliminación del campo personalizado

Instalación

Requisitos previos

• Python 3.10 o superior
• Una cuenta de ClickUp con una clave de API

Usando uv (recomendado)

Cuando se usa uv no se necesita ninguna instalación específica. Usaremos uvx para ejecutar directamente clickup-mcp-server.

uv --directory "/path/to/clickup-mcp-server" run clickup-mcp-server --api-key YOUR_API_KEY

O usa un archivo .env (consulta la sección de Configuración).

Usando PIP

Alternativamente, puedes instalar clickup-mcp-server vía pip:

pip install clickup-mcp-server

Después de la instalación, puedes ejecutarlo como un script usando:

python -m clickup_mcp_server --api-key YOUR_API_KEY

Configuración

Clave de API

Necesitas una clave de API de ClickUp para usar este servidor. Puedes obtener una en Configuración de API de ClickUp.

La clave de API se puede proporcionar de dos maneras:

1. Argumento de línea de comandos: --api-key YOUR_API_KEY
2. Variable de entorno en un archivo .env:

   CLICKUP_API_KEY=your_api_key_here
   

Uso con Claude Desktop

Añade esto a tu claude_desktop_config.json:

"mcpServers": {
  "clickup": {
    "command": "uvx",
    "args": ["clickup-mcp-server", "--api-key", "YOUR_API_KEY"]
  }
}

"mcpServers": {
  "clickup": {
    "command": "docker",
    "args": ["run", "--rm", "-i", "-e", "CLICKUP_API_KEY=YOUR_API_KEY", "mcp/clickup"]
  }
}

"mcpServers": {
  "clickup": {
    "command": "python",
    "args": ["-m", "clickup_mcp_server", "--api-key", "YOUR_API_KEY"]
  }
}

Uso con VS Code

Para la instalación manual, añade el siguiente bloque JSON a tu archivo de Configuración de Usuario (JSON) en VS Code. Puedes hacerlo presionando Ctrl + Shift + P y escribiendo Preferences: Open Settings (JSON). Opcionalmente, puedes añadirlo a un archivo llamado .vscode/mcp.json en tu espacio de trabajo. Esto te permitirá compartir la configuración con otros.

Ten en cuenta que la clave mcp no es necesaria en el archivo .vscode/mcp.json.

{
  "mcp": {
    "servers": {
      "clickup": {
        "command": "uvx",
        "args": ["clickup-mcp-server"],
        "env": {
          "CLICKUP_API_KEY": "YOUR_API_KEY"
        }
      }
    }
  }
}

Para instalación con Docker:

{
  "mcp": {
    "servers": {
      "clickup": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "-e", "CLICKUP_API_KEY=YOUR_API_KEY",
          "mcp/clickup"
        ]
      }
    }
  }
}

Uso con Zed

Añade a tu settings.json de Zed:

"context_servers": [
  "mcp-server-clickup": {
    "command": {
      "path": "uvx",
      "args": ["clickup-mcp-server"]
    },
    "env": {
      "CLICKUP_API_KEY": "YOUR_API_KEY"
    }
  }
],

"context_servers": {
  "mcp-server-clickup": {
    "command": {
      "path": "python",
      "args": ["-m", "clickup_mcp_server"]
    },
    "env": {
      "CLICKUP_API_KEY": "YOUR_API_KEY"
    }
  }
},

Ejemplos de Escenarios de Uso

Gestión de Tareas con Claude

Claude puede ayudarte a gestionar tus tareas de ClickUp:

1. Crear un Plan de Tarea: Pide a Claude que cree un plan basado en una tarea específica en ClickUp. Claude:

   • Encontrará la tarea por nombre o ID
   • Analizará su descripción y subtareas
   • Generará un plan estructurado para completar la tarea

2. Automatización de Tareas: Para una tarea que contenga instrucciones relacionadas con código, Claude puede:

   • Obtener los detalles de la tarea desde ClickUp
   • Actualizar el estado de la tarea a "En Progreso"
   • Implementar el código según los requisitos de la tarea
   • Marcar las subtareas como completadas
   • Actualizar el estado a "Listo para Revisión" al terminar

3. Informes de Tareas: Pide a Claude que genere resúmenes de tareas con estados específicos:

   • Obtener todas las tareas marcadas como "En Progreso"
   • Compilar un informe de estado con estimaciones de finalización
   • Crear nuevas tareas para bloqueos o dependencias

4. Gestión de Campos Personalizados: Claude puede trabajar con campos personalizados para mejorar tu flujo de trabajo:

   • Listar todos los campos personalizados en un proyecto para ver los metadatos disponibles
   • Establecer valores de campos personalizados como "GitHub Pull Request URL" al crear PRs
   • Actualizar campos de seguimiento del proyecto como "Sprint", "Story Points" o "Priority"
   • Ejemplo: "Crea un PR para esta rama y añade la URL de GitHub al campo personalizado 'GitHub Pull Request URL' en la tarea de ClickUp relacionada"

Depuración

Ejecuta tu servidor con la bandera -v o -vv para mayor verbosidad:

uvx clickup-mcp-server -vv

Puedes usar el inspector de MCP para depurar el servidor:

npx @modelcontextprotocol/inspector uvx clickup-mcp-server

Desarrollo

Configuración del Entorno de Desarrollo

1. Clona el repositorio:

   git clone https://github.com/yourusername/clickup-mcp-server.git
   cd clickup-mcp-server
   

2. Instala las dependencias de desarrollo:

   uv pip install -e ".[dev]"
   

3. Ejecuta las pruebas:

   pytest
   

Compilación con Docker

Compila la imagen de Docker:

docker build -t mcp/clickup .

Estado de Implementación

Este servidor MCP implementa la mayoría de las funciones esenciales de ClickUp. A continuación se muestra un desglose detallado de las funciones implementadas y las planificadas para su implementación futura.

Gestión de Tareas ✅

Todas las funciones principales de gestión de tareas han sido implementadas:

Organización del Espacio de Trabajo ✅

Todas las funciones de organización del espacio de trabajo han sido implementadas:

Funciones Varias 🔧

Algunas funciones avanzadas están implementadas, con otras planificadas para futuras versiones:

Leyenda:

• ✅ Implementado
• 🔄 Planificado o en progreso

Licencia

Este servidor MCP está licenciado bajo la Licencia MIT. Esto significa que eres libre de usar, modificar y distribuir el software, sujeto a los términos y condiciones de la Licencia MIT. Para más detalles, consulta el archivo LICENSE en el repositorio del proyecto. EOF < /dev/null