ClickUp

Integra asistentes de IA con ClickUp para productividad y gestión de proyectos.

GitHub
49

Documentación

ClickUp MCP para Asistentes de IA

Servidor de Model Context Protocol (MCP) que permite a los asistentes de IA interactuar con espacios de trabajo de ClickUp. Obtén contexto completo de tareas con comentarios e imágenes, busca en proyectos, crea y actualiza tareas, colabora mediante comentarios y registra tiempo, todo a través de lenguaje natural.

Este MCP vs el MCP Oficial de ClickUp

Ver también: Documentación oficial del MCP de ClickUp

CaracterísticaEste MCPMCP Oficial de ClickUp
ConfiguraciónInstalación local con npm/npxMCP remoto (sin instalación)
AutenticaciónSolo clave APISolo OAuth
Contexto de tareasCompleto con comentarios, historial de estados, imágenes integradasRequiere múltiples llamadas de herramientas para contexto completo
Soporte de imágenesLectura y escritura: imágenes integradas con presupuesto inteligente de tamaño, y cargas de ![](local/path.png) automáticasCarga mediante llamadas de herramientas separadas; base64 limitado a ~200KB
BúsquedaBúsqueda difusa en tareas recientes (alcance limitado)Base de datos de búsqueda completa de ClickUp
DocumentosOperaciones CRUDCRUD + búsqueda de documentos
Seguimiento de tiempoVer y crear entradasTemporizadores y entradas
Integración de chatNo compatibleCompatible
Aplicaciones conectadasNo compatibleBúsqueda conectada
Ideal paraHerramientas de codificación, automatización, recopilación de contextoAplicaciones de chat, gestión de tareas
SoporteComunidad (código abierto)ClickUp oficial

Elige este MCP cuando:

  • Necesites contexto enriquecido de tareas con imágenes integradas para herramientas de codificación con IA
  • Quieras escribir capturas de pantalla en tickets mediante rutas de archivo locales (al ejecutarse localmente, lee el archivo directamente en lugar de usar base64)
  • Necesites autenticación con clave API para automatización o pipelines de CI/CD
  • Quieras el modo read-minimal optimizado para flujos de trabajo de desarrollo

Elige el MCP Oficial cuando:

  • Necesites autenticación OAuth para cumplimiento de seguridad empresarial
  • Necesites funciones de integración de chat o búsqueda conectada
  • Quieras soporte oficial y sin instalación local

Lo Que Puedes Hacer

Convierte lenguaje natural en potentes acciones de ClickUp:

Codificación y Desarrollo Agéntico:

  • "Mira CU-abc123, ¿puedes encontrar el código relevante?"
  • "¿Puedes construir el panel como se describe en https://app.clickup.com/t/12a23b45c??"
  • "Revisa la tarea CU-xyz789 y corrige los errores mencionados en los comentarios"
  • "Implementa los endpoints de API descritos en la tarea de integración"

Seguimiento de Tiempo y Productividad:

  • "Reserva 2 horas para la reunión con el cliente en el proyecto XYZ"
  • "¿Cuánto tiempo dediqué a tareas de desarrollo esta semana?"
  • "Registra 30 minutos para revisión de código en la función de autenticación"

Búsqueda Inteligente y Descubrimiento:

  • "¿En qué tarea mencioné la importación de CSV?"
  • "Encuentra todas las tareas relacionadas con la integración de la pasarela de pagos"
  • "Muéstrame tareas donde los usuarios reportaron problemas de inicio de sesión"

Gestión del Flujo de Trabajo Diario:

  • "¿Qué necesito hacer hoy?"
  • "Crea una tarea para corregir el error del panel en la lista de frontend"
  • "Actualiza la tarea de documentación de API al estado 'en revisión'"
  • "¿Qué tareas están bloqueando el lanzamiento de la aplicación móvil?"

Contexto Enriquecido y Colaboración:

  • "Muéstrame todos los comentarios sobre la tarea de autenticación de usuarios"
  • "¿Cuál es la última actualización sobre la migración de la base de datos?"
  • "Añade un comentario a la tarea de diseño sobre los nuevos wireframes"

Gestión de Documentos:

  • "Encuentra documentos sobre publicación de empleos en el espacio hauptsache.net"
  • "Busca documentación de API en todos los espacios"
  • "Lee la documentación de API en el espacio de desarrollo"
  • "Crea un nuevo documento de requisitos para el proyecto de la aplicación móvil"
  • "Actualiza las notas de la reunión con las decisiones de hoy"
  • "¿Qué documentos hay en el espacio de estrategia de producto?"

Características Clave

🔍 Búsqueda Inteligente

  • Coincidencia difusa en nombres de tareas, descripciones y comentarios
  • Soporte de búsqueda multilingüe para equipos internacionales
  • Filtros por asignados, proyectos, estado y metadatos

💬 Contexto Completo

  • Historiales de comentarios y discusiones de equipo (hasta 250 comentarios de nivel superior), incluyendo respuestas en hilos
  • Descripciones de tareas con imágenes integradas
  • Descripciones de listas y pautas de proyecto
  • Contenido de documentos con navegación de páginas
  • Acceso al historial completo de tareas y decisiones

⏱️ Seguimiento de Tiempo

  • Registro de entradas de tiempo con descripciones
  • Visualización de registros y entradas de tiempo históricos
  • Consulta de entradas de tiempo por tarea o rango de fechas

📋 Gestión de Tareas y Documentos

  • Crear y actualizar tareas con descripciones en markdown
  • Crear, leer y actualizar documentos y páginas
  • Añadir comentarios y colaborar con miembros del equipo
  • Gestionar prioridades, fechas de vencimiento, asignados y etiquetas
  • Manejar estimaciones de tiempo y valores de campos personalizados

🔒 Características de Seguridad

  • Descripciones de Solo Anexión: Los campos de descripción nunca se sobrescriben; el contenido nuevo se anexa de forma segura con marcas de tiempo
  • Actualizaciones Normales de Campos: Estado, prioridad, asignados, etiquetas y fechas se pueden actualizar normalmente (fácilmente reversibles mediante el historial de ClickUp)

Instalación

Requisitos Previos

Para todos los métodos de instalación, necesitarás:

  • Tu CLICKUP_API_KEY (Icono de Perfil > Configuración > Apps > Token de API ~ generalmente comienza con pk_)
  • Tu CLICKUP_TEAM_ID (El número de 7 a 10 dígitos en la URL cuando estás en la configuración)

Opción 1: Paquete MCPB (Recomendado para Claude Desktop)

Descarga el paquete precompilado desde nuestra página de versiones. Este método no requiere instalación de Node.js.

Obtendrás una pantalla de configuración donde se te pedirá ingresar tu clave API e ID de equipo.

Opción 2: Instalación NPX

Este método se actualiza automáticamente a la última versión y es preferido para usuarios que quieren las funciones más recientes.

Para Claude Desktop, Windsurf, Cursor y otros:

Añade lo siguiente a tu archivo de configuración MCP:

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": [
        "@hauptsache.net/clickup-mcp@latest"
      ],
      "env": {
        "CLICKUP_API_KEY": "your_api_key",
        "CLICKUP_TEAM_ID": "your_team_id"
      }
    }
  }
}

Reemplaza your_api_key y your_team_id con tus credenciales reales de ClickUp.

Dónde añadir esta configuración:

  • Claude Desktop: Configuración > Desarrollador > Editar Configuración
  • Windsurf: Añade a tu archivo de configuración MCP
  • Cursor: Configura a través del panel de configuración MCP

Opción 3: Integración con Herramientas de Codificación

Claude Code (CLI):

claude mcp add --scope user clickup \
  --env CLICKUP_API_KEY=YOUR_KEY \
  --env CLICKUP_TEAM_ID=YOUR_ID \
  --env CLICKUP_MCP_MODE=read-minimal \
  --env MAX_IMAGES=16 \
  --env MAX_RESPONSE_SIZE_MB=4 \
  -- npx -y @hauptsache.net/clickup-mcp

Claude Code puede manejar muchas imágenes, por lo tanto se recomiendan límites aumentados.

Nota el CLICKUP_MCP_MODE=read-minimal. Esta es mi recomendación de uso, pero siéntete libre de usar uno de los otros modos.

OpenAI Codex: Añade estas líneas a tu archivo ~/.codex/config.toml:

[mcp_servers.clickup]
command = "npx"
args = ["-y", "@hauptsache.net/clickup-mcp@latest"]
env = { "CLICKUP_API_KEY" = "YOUR_KEY", "CLICKUP_TEAM_ID" = "YOUR_ID", "CLICKUP_MCP_MODE" = "read-minimal" }

Codex parece no poder manejar imágenes de MCP. Consulta este problema para más detalles.

Nota el CLICKUP_MCP_MODE=read-minimal. Esta es mi recomendación de uso, pero siéntete libre de usar uno de los otros modos.

Modos MCP y Herramientas Disponibles

El MCP de ClickUp soporta tres modos operativos para equilibrar funcionalidad, seguridad y rendimiento:

  • 🚀 read-minimal: Perfecto para asistentes de codificación con IA y recopilación de contexto
  • 📖 read: Acceso completo de solo lectura para exploración de proyectos y comprensión del flujo de trabajo
  • ✏️ write (Predeterminado): Funcionalidad completa para gestión de tareas y flujos de productividad
Herramientaread-minimalreadwriteDescripción
getTaskById✅✅✅Obtén detalles completos de tareas incluyendo comentarios (con respuestas en hilos), imágenes y metadatos
addComment❌❌✅Añade comentarios a tareas, o responde dentro de un hilo de comentarios mediante parent_comment_id
editComment❌❌✅Corrige tu propio comentario dentro de 24 horas en lugar de publicar un seguimiento
updateTask❌❌✅Actualiza tareas (estado, prioridad, asignados, etc.); las descripciones se pueden anexar o reemplazar por completo
createTask❌❌✅Crea nuevas tareas con soporte completo de markdown
searchTasks✅✅✅Encuentra tareas por contenido, palabras clave, asignados o contexto de proyecto
searchSpaces❌✅✅Explora la estructura del espacio de trabajo, organización de proyectos y documentos
getListInfo❌✅✅Obtén detalles de listas y estados disponibles para la creación de tareas
updateListInfo❌❌✅ACTUALIZACIONES SEGURAS DE SOLO ANEXIÓN a descripciones de listas (preserva el contenido existente)
getTimeEntries❌✅✅Ver entradas de tiempo y analizar tiempo invertido en proyectos
createTimeEntry❌❌✅Registrar entradas de tiempo para seguimiento de tareas
readDocument❌✅✅Obtén detalles de documentos, estructura de páginas y contenido con navegación
searchDocuments❌✅✅Busca documentos por nombre y espacio con coincidencia difusa y filtrado por espacio
updateDocumentPage❌❌✅Actualiza contenido o nombre de páginas existentes con modos de reemplazo/anexión
createDocumentOrPage❌❌✅Crea nuevos documentos con primera página, o añade páginas/subpáginas a documentos existentes

Configuración del Modo

Añade el modo a tu configuración MCP:

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["-y", "@hauptsache.net/clickup-mcp@latest"],
      "env": {
        "CLICKUP_API_KEY": "your_api_key",
        "CLICKUP_TEAM_ID": "your_team_id",
        "CLICKUP_MCP_MODE": "read"
      }
    }
  }
}

Configuración

Este servidor MCP se puede configurar usando variables de entorno. En el instalador de la extensión de escritorio (.mcpb), la clave API, ID de equipo, idioma principal, límite de tamaño de carga y ventana de edición de comentarios se ofrecen como campos de formulario; las variables restantes deben configurarse directamente en el entorno del servidor.

  • CLICKUP_API_KEY: (Requerido) Tu clave API de ClickUp.
  • CLICKUP_TEAM_ID: (Requerido) Tu ID de Equipo de ClickUp (anteriormente ID de Espacio de Trabajo).
  • CLICKUP_MCP_MODE: (Opcional) Controla qué herramientas están disponibles. Opciones: read-minimal, read, write (predeterminado).
  • MAX_IMAGES: (Opcional) El número máximo de imágenes a devolver para una tarea en getTaskById. El valor predeterminado es 4.
  • MAX_RESPONSE_SIZE_MB: (Opcional) El tamaño máximo de respuesta en megabytes para getTaskById. Utiliza presupuesto inteligente de tamaño para incluir las imágenes más importantes dentro del límite. El valor predeterminado es 1.
  • MAX_UPLOAD_SIZE_MB: (Opcional) El tamaño máximo de una sola imagen cargada al escribir comentarios o descripciones. El valor predeterminado es 10.
  • CLICKUP_COMMENT_EDIT_WINDOW_HOURS: (Opcional) Cuánto tiempo después de la creación editComment puede reescribir un comentario. El valor predeterminado es 24. Configúralo en 0 para deshabilitar la edición de comentarios por completo.
  • CLICKUP_PRIMARY_LANGUAGE: (Opcional) Una pista para el idioma principal utilizado en tus tareas de ClickUp (por ejemplo, "de" para alemán, "en" para inglés). Esto ayuda a la herramienta searchTask a proporcionar orientación más adaptada en su descripción para búsquedas multilingües.
  • LANG: (Opcional) Si CLICKUP_PRIMARY_LANGUAGE no está configurado, el MCP verificará esta variable de entorno estándar (por ejemplo, "en_US.UTF-8", "de_DE") como respaldo para inferir el idioma principal.

Orientación de Búsqueda Consciente del Idioma

La descripción de la herramienta searchTask se ajustará dinámicamente según el idioma principal detectado:

  • Si CLICKUP_PRIMARY_LANGUAGE o LANG sugiere un idioma principal conocido (por ejemplo, alemán), la descripción de la herramienta recomendará específicamente proporcionar términos de búsqueda tanto en inglés como en ese idioma detectado (por ejemplo, alemán) para obtener resultados óptimos.
  • Si no se detecta un idioma principal, se proporcionará una recomendación más general para espacios de trabajo multilingües.

Esta función tiene como objetivo mejorar la efectividad de la búsqueda cuando el idioma de las consultas del usuario (a menudo inglés) difiere del idioma de las tareas en ClickUp, sin que el propio MCP realice traducciones. La responsabilidad de proporcionar términos de búsqueda bilingües sigue recayendo en el agente que llama al MCP, pero el MCP ofrece consejos más específicos si tiene una pista de idioma.

Soporte de formato Markdown

Las descripciones de tareas y la documentación de listas admiten formato markdown completo:

Ejemplos

Creación de tareas con Markdown:

Create a task called "API Integration" with description:
# API Integration Requirements

## Authentication
- Implement OAuth 2.0 flow
- Add JWT token validation
- **Priority**: High security standards

## Endpoints
1. `/api/users` - User management
2. `/api/data` - Data retrieval
3. `/api/webhook` - Event notifications

## Testing
- [ ] Unit tests for auth flow
- [ ] Integration tests
- [ ] Load testing with 1000+ concurrent users

> **Note**: This replaces the legacy REST implementation

See related task: https://app.clickup.com/t/abc123

Actualizaciones de solo añadido (seguras): Al actualizar descripciones de tareas, el contenido se añade de forma segura:

[Existing task description content]

---
**Edit (2024-01-15):** Added new acceptance criteria based on client feedback:
- Must support mobile responsive design
- Performance requirement: < 2s load time

Esto garantiza que nunca se pierda contenido existente mientras se mantiene un rastro de auditoría claro.

Escribir imágenes en tickets

addComment, editComment, createTask y updateTask aceptan imágenes como markdown ordinario. Debido a que este servidor se ejecuta localmente, lee el archivo por sí mismo, por lo que una ruta local es suficiente:

Ist umgesetzt. So sieht es aus:

**1. Login öffnen** – der Kunde gibt nur seine E-Mail-Adresse ein.

![Die Login-Maske fragt nur nach der E-Mail](/Users/me/shots/login.png)

Fuentes aceptadas: rutas de archivo locales, URI data:, URL http(s) (descargadas y luego re-subidas), y URL de adjuntos existentes de ClickUp (incrustadas sin re-subir).

Notas:

  • Prefiere rutas sobre base64. Una ruta cuesta unos pocos tokens; la misma captura de pantalla como URI data: cuesta aproximadamente 4/3 de su tamaño de archivo en la solicitud.
  • El título se convierte en el nombre del archivo adjunto, y ese nombre es lo que ClickUp muestra debajo de la imagen, así que escribe un título que se lea bien.
  • Una imagen dentro de una lista numerada rompe la numeración de ClickUp. Escribe los pasos del tutorial como líneas en negrita con la imagen entre ellas, como arriba.
  • Solo se suben archivos PNG/JPEG/GIF/WebP reales: se verifica el contenido, no la extensión. Un archivo que falla aborta la escritura: addComment, editComment y updateTask informan cada referencia rota y no cambian nada, para que el markdown pueda corregirse y la llamada reintentarse sin crear duplicados. createTask valida sus imágenes antes de crear la tarea; solo una subida que falla posteriormente se informa como advertencia, ya que la tarea ya existe en ese punto.
  • Los adjuntos siempre pertenecen a una tarea, por lo que las páginas de documentos no pueden incrustar subidas de esta manera.

Rendimiento y limitaciones

Optimizado para flujos de trabajo de IA:

  • Procesamiento inteligente de imágenes: El presupuesto inteligente de tamaño prioriza las imágenes más recientes respetando tanto el límite de cantidad (MAX_IMAGES, predeterminado: 4) como el límite de tamaño total de respuesta (MAX_RESPONSE_SIZE_MB, predeterminado: 1MB)
  • Alcance de búsqueda: Busca dentro de las 1000-3000 tareas más recientes para evitar alcanzar los límites de tasa (el número exacto varía según el endpoint)
  • Resultados de búsqueda: Devuelve hasta 50 coincidencias más relevantes para evitar inundar al agente con demasiados resultados

Alcance actual:

  • Enfocado en operaciones a nivel de tarea en lugar de gestión masiva del espacio de trabajo
  • Optimizado para flujos de trabajo conversacionales de IA en lugar de migración de datos
  • Diseñado para la mejora de la productividad, no para operaciones administrativas

Estas limitaciones garantizan un rendimiento confiable mientras cubren los casos de uso más comunes tanto para el contexto de desarrollo como para la gestión de productividad.

Licencia

MIT