ClickUp

Servidor MCP de ClickUp

Un servidor de Protocolo de Contexto de Modelo (MCP) que permite a los asistentes de IA interactuar con la API de gestión de tareas de ClickUp. Este servidor proporciona capacidades integrales de gestión de tareas a través de lenguaje natural, centrándose en flujos de trabajo de proyectos esenciales en lugar del conjunto completo de funciones de ClickUp.

Creado por el equipo de Diversio para una gestión de tareas optimizada impulsada por IA.

🚀 Qué Proporciona Este Servidor

✅ Gestión de Tareas Principal

• Operaciones CRUD de Tareas - Crear, leer, actualizar y eliminar tareas
• Organización de Tareas - Navegar por espacios, carpetas y listas
• Búsqueda y Filtrado de Tareas - Encontrar tareas por varios criterios
• Comentarios y Colaboración - Leer y crear comentarios en tareas
• Gestión de Usuarios y Asignaciones - Listar usuarios, buscar por nombre/correo, asignar a tareas
• Gestión de Estados - Actualizar y rastrear estados de tareas

✅ Funciones de Productividad

• Operaciones Masivas - Actualizar o mover varias tareas a la vez
• Seguimiento de Tiempo - Registrar tiempo y ver horas rastreadas
• Plantillas de Tareas - Crear tareas a partir de plantillas predefinidas (informe de errores, solicitud de funciones, revisión de código)
• Cadenas de Tareas - Crear secuencias de tareas dependientes
• Analíticas de Equipo - Ver distribución de carga de trabajo y métricas de finalización

✅ Soporte Flexible de IDs

• IDs estándar de ClickUp (abc123)
• Patrones de ID personalizados (gh-123, bug-456)
• URLs de ClickUp (https://app.clickup.com/t/abc123)
• Formato hash (#123)

❌ Lo Que NO Está Incluido

Este servidor se centra en lo esencial de la gestión de tareas. No compatible:

• Documentos de ClickUp
• Pizarras
• Paneles de control
• Automatizaciones/Flujos de trabajo
• Metas/Objetivos
• Gestión de archivos/adjuntos
• Gestión de webhooks
• Operaciones avanzadas de campos personalizados
• Vistas de calendario
• Integración de formularios

Cobertura de API: ~30-40% de la API completa de ClickUp, cubriendo los flujos de trabajo de gestión de tareas más comunes.

Instalación

Inicio Rápido (Recomendado)

# Install from GitHub (latest)
uvx --from git+https://github.com/DiversioTeam/clickup-mcp clickup-mcp

# Or from PyPI (when published)
uvx clickup-mcp

Instalación para Desarrollo

git clone https://github.com/DiversioTeam/clickup-mcp
cd clickup-mcp
uv sync
uv run clickup-mcp

Configuración

Configuración de la Clave de API

# Set your ClickUp API key
uvx clickup-mcp set-api-key YOUR_API_KEY_HERE

# Or set environment variable
export CLICKUP_MCP_API_KEY=your_api_key

Cómo Obtener Tu Clave de API de ClickUp

Instrucciones paso a paso:

1. Inicia sesión en ClickUp en https://app.clickup.com
2. Navega a Configuración:
   • Haz clic en tu avatar/foto de perfil en la esquina inferior izquierda
   • Selecciona "Configuración" en el menú desplegable
3. Ve a la sección de Aplicaciones:
   • En la barra lateral izquierda, haz clic en "Aplicaciones"
   • Luego haz clic en "API" (o ve directamente a https://app.clickup.com/settings/apps)
4. Genera el Token de API:
   • Haz clic en el botón "Generar" para crear un nuevo token de API personal
   • Importante: ¡Este token solo se mostrará una vez!
5. Copia y Guarda:
   • Copia el token generado inmediatamente
   • Guárdalo de forma segura (se recomienda un gestor de contraseñas)
   • Configúralo usando: uvx clickup-mcp set-api-key YOUR_TOKEN_HERE

Notas importantes:

• Los tokens de API personales tienen los mismos permisos que tu cuenta de usuario
• Mantén tu token seguro: trátalo como una contraseña
• Si pierdes el token, deberás generar uno nuevo
• Los tokens no caducan, pero pueden revocarse en la misma página de configuración

Uso con Asistentes de IA

Claude Code (CLI)

Añade a ~/.config/claude-code/mcp-settings.json:

{
  "servers": {
    "clickup": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/DiversioTeam/clickup-mcp.git", "clickup-mcp"]
    }
  }
}

Claude Desktop

Añade a tu archivo de configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "clickup": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/DiversioTeam/clickup-mcp.git", "clickup-mcp"]
    }
  }
}

VS Code

VS Code tiene un excelente soporte de MCP tanto mediante integración nativa como extensiones. Hay múltiples opciones de configuración disponibles:

Opción 1: MCP nativo de VS Code (Recomendado)

VS Code ahora tiene soporte MCP integrado con GitHub Copilot y Agent Mode. Añade a tu espacio de trabajo:

Crea .vscode/mcp.json en tu proyecto:

{
  "servers": {
    "clickup": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/DiversioTeam/clickup-mcp.git", "clickup-mcp"]
    }
  }
}

O añade a la Configuración de Usuario de VS Code:

1. Abre la Paleta de Comandos (Ctrl+Shift+P / Cmd+Shift+P)
2. Ejecuta "Preferencias: Abrir Configuración de Usuario (JSON)"
3. Añade a la configuración:

{
  "mcp": {
    "servers": {
      "clickup": {
        "command": "uvx",
        "args": ["--from", "git+https://github.com/DiversioTeam/clickup-mcp.git", "clickup-mcp"]
      }
    }
  }
}

Opción 2: Extensiones de VS Code con Soporte MCP

Extensión Copilot MCP:

1. Instala "Copilot MCP" desde el Marketplace de VS Code
2. Busca, gestiona e instala servidores MCP directamente desde VS Code
3. La extensión te ayudará a configurar el servidor MCP de ClickUp

Cline (Asistente de Codificación con IA):

1. Instala la extensión "Cline" para codificación avanzada con IA y soporte MCP
2. Configura el servidor MCP de ClickUp a través de la configuración de Cline

Gestión de Servidores MCP en VS Code

1. Abre la Paleta de Comandos (Ctrl+Shift+P / Cmd+Shift+P)
2. Ejecuta "MCP: List Servers" para ver los servidores configurados
3. Selecciona el servidor de ClickUp para Iniciar/Detener/Reiniciar o ver registros
4. Usa "MCP: Show Output" para depuración

Verificar la Configuración de VS Code

1. Asegúrate de que tu clave de API de ClickUp esté configurada: uvx clickup-mcp set-api-key YOUR_KEY
2. En VS Code, pregunta a GitHub Copilot: "¿Puedes listar mis espacios de ClickUp usando herramientas MCP?"
3. Verifica el estado del servidor MCP con la Paleta de Comandos → "MCP: List Servers"

Herramientas Disponibles (28 Herramientas)

📝 Gestión de Tareas

• create_task - Crear nuevas tareas
• get_task - Obtener detalles de tareas (admite varios formatos de ID)
• update_task - Actualizar propiedades de tareas
• delete_task - Eliminar tareas
• create_task_from_template - Crear a partir de plantillas predefinidas
• create_task_chain - Crear secuencias de tareas dependientes

🔍 Descubrimiento de Tareas

• list_tasks - Listar tareas con opciones de filtrado
• search_tasks - Buscar tareas por texto y criterios
• get_subtasks - Obtener todas las subtareas de una tarea principal
• get_task_comments - Obtener comentarios en tareas
• create_task_comment - Crear comentarios en tareas

👥 Asignación y Estado

• get_task_status - Obtener el estado actual de la tarea
• update_task_status - Cambiar el estado de la tarea
• get_assignees - Listar asignados de tareas
• assign_task - Asignar usuarios a tareas

🗂️ Navegación

• list_spaces - Listar todos los espacios en el espacio de trabajo
• list_folders - Listar carpetas en un espacio
• list_lists - Listar todas las listas
• find_list_by_name - Encontrar listas por nombre

⚡ Operaciones Masivas

• bulk_update_tasks - Actualizar varias tareas a la vez
• bulk_move_tasks - Mover varias tareas a diferentes listas

⏱️ Seguimiento de Tiempo

• get_time_tracked - Obtener tiempo registrado para usuarios/períodos
• log_time - Registrar tiempo dedicado a tareas

📊 Analíticas

• get_team_workload - Ver distribución de tareas entre miembros del equipo
• get_task_analytics - Obtener métricas de velocidad y tasas de finalización

👤 Gestión de Usuarios

• list_users - Listar todos los usuarios en el espacio de trabajo
• get_current_user - Obtener detalles del usuario autenticado actual
• find_user_by_name - Encontrar usuarios por nombre o correo electrónico

Ejemplos de Uso

Comandos en Lenguaje Natural

Pregunta a tu asistente de IA:

"Create a bug report for login issues in the Development list"
"Show me all high-priority tasks assigned to me"
"Move all completed tasks from Sprint 1 to Archive"
"Log 2 hours on task gh-123 for debugging"
"What's our team's current workload?"
"Create a task chain: Design → Implement → Test → Deploy"
"Add a comment to task GH-3761 saying 'testing complete'"
"Get all comments on the bug report task"
"Comment on task abc123 and assign it to John"

Plantillas de Tareas

"Create a bug report template for the payment processing issue"
"Use the code review template for PR #456"
"Create a feature request for dark mode"

Consultas de Analíticas

"What's our task completion rate this month?"
"Who has the most tasks assigned?"
"Show me time tracked on the API project"

Desarrollo

Ejecutar Pruebas

# Run all tests (62 tests)
uv run pytest

# Run with coverage
uv run pytest --cov=clickup_mcp

# Run specific test
uv run pytest tests/test_client.py::test_create_task

Calidad de Código

# Check code style
uv run ruff check .

# Format code
uv run ruff format .

# Type checking
uv run mypy src/

Solución de Problemas

Verificar Configuración

# Verify API key is configured
uv run clickup-mcp check-config

# Test API connection
uv run clickup-mcp test-connection

Modo de Depuración

# Run with debug logging
uv run clickup-mcp --debug

Pruebas Locales con Claude Code

# Add the server for local testing with Claude Code CLI
claude mcp add clickup-local -- uv run clickup-mcp

# Then you can test the functionality immediately
# Example: List spaces, create tasks, add comments, etc.

Limitaciones Técnicas

• Límite de Velocidad: Sin límite de velocidad integrado (ClickUp: 100 solicitudes/min)
• Paginación: Soporte de paginación limitado
• Caché: No se implementa caché de respuestas
• Campos Personalizados: Existen modelos pero con soporte limitado de herramientas
• Recuperación de Errores: Manejo básico de errores sin reintentos sofisticados

Contribuciones

¡Damos la bienvenida a las contribuciones! Áreas de enfoque:

Mejoras Prioritarias

• Manejo mejorado de errores y lógica de reintentos
• Implementación de caché de respuestas
• Mejor soporte de paginación
• Soporte ampliado de campos personalizados

Cómo Contribuir

1. Haz un fork del repositorio
2. Crea una rama de funcionalidad (git checkout -b feature/improvement)
3. Haz cambios y añade pruebas
4. Asegúrate de que todas las pruebas pasen (uv run pytest)
5. Ejecuta el linting (uv run ruff check .)
6. Envía una Solicitud de Extracción (Pull Request)

Configuración de Desarrollo

git clone https://github.com/yourusername/clickup-mcp
cd clickup-mcp
uv sync
uv run pytest  # Ensure tests pass

Soporte

• Problemas: Problemas de GitHub
• Discusiones: Discusiones de GitHub
• Correo electrónico: tech@diversio.com

Licencia

Licencia MIT - consulta el archivo LICENCIA para más detalles.

Agradecimientos

• Creado por el equipo de Diversio
• Impulsado por Protocolo de Contexto de Modelo
• Utiliza API v2 de ClickUp