ClickUp

Un servidor MCP para ClickUp, que permite a los asistentes de IA interactuar y gestionar tareas dentro de tus espacios de trabajo de ClickUp.

GitHub

Documentación

Servidor MCP de ClickUp

Una implementación del servidor del Protocolo de Contexto de Modelo para la integración con ClickUp, que permite a los asistentes de IA interactuar con los espacios de trabajo de ClickUp.

Este servidor se ejecuta a través de Stdio según la especificación MCP cuando es invocado por un cliente MCP.

Inicio Rápido

Este servidor utiliza tu Token de API Personal de ClickUp para la autenticación.

Genera un Token de API Personal: En la configuración de tu ClickUp, navega a "Mi Configuración" > "Aplicaciones" y genera un token.
Configura tu Cliente MCP (por ejemplo, Claude para Desktop): Establece la variable de entorno requerida al configurar el servidor para tu cliente.

Ejemplo de fragmento de configuración para un cliente MCP:

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["@nazruden/clickup-server"],
      "env": {
        "CLICKUP_PERSONAL_TOKEN": "your_personal_api_token_here"
      }
    }
  }
}

Reinicia tu Cliente MCP.

El servidor será descargado e iniciado automáticamente por el cliente MCP cuando sea necesario.

Instalación a través de Smithery

Para instalar ClickUp MCP Server para Claude Desktop automáticamente a través de Smithery:

npx -y @smithery/cli install @Nazruden/clickup-mcp-server --client claude

Variables de Entorno

Requeridas

CLICKUP_PERSONAL_TOKEN: Tu Token de API Personal de ClickUp. Esto es esencial para que el servidor se autentique con la API de ClickUp.

Opcionales

LOG_LEVEL: Nivel de registro para el servidor. Soporta error, warn, info, debug. El valor predeterminado es info.
ENCRYPTION_KEY: Una clave persistente codificada en hexadecimal de 32 bytes. El sistema de configuración (src/config/app.config.ts) carga o genera esta clave, y src/security.ts contiene funciones de cifrado/descifrado. Sin embargo, este mecanismo actualmente no se utiliza para cifrar el CLICKUP_PERSONAL_TOKEN dentro del flujo de autenticación de Token de API Personal del ClickUpService.
PORT: Puerto del servidor. No se utiliza en el modo predeterminado del servidor MCP Stdio, pero podría ser relevante si se agregaran explícitamente transporte HTTP o características HTTP adicionales (como un endpoint separado de verificación de salud). El valor predeterminado es 3000 en la configuración si se lee.

Herramientas Disponibles

Las siguientes herramientas MCP están actualmente implementadas:

Gestión de Tareas

clickup_create_task: Crear una nueva tarea en una lista de ClickUp.
- Requiere: list_id, name.
- Opcional: description, status, priority, assignees, due_date, time_estimate, tags.
clickup_update_task: Actualizar las propiedades de una tarea existente.
- Requiere: task_id.
- Opcional: Cualquier propiedad escribible de ClickUpTask.

Gestión de Equipos y Listas

clickup_get_teams: Recuperar todos los equipos accesibles (Espacios de Trabajo en la API v2 de ClickUp).
clickup_get_lists: Obtener todas las listas en una carpeta específica.
- Requiere: folder_id.

Gestión de Tableros

clickup_create_board: Crear un nuevo tablero en un espacio de ClickUp.
- Requiere: space_id, name.

Gestión de Espacios

clickup_get_spaces: Recupera todos los Espacios para un Espacio de Trabajo (Equipo) dado.
- Requiere: team_id (ID del Espacio de Trabajo).
- Opcional: archived (booleano, el valor predeterminado es false).
clickup_create_space: Crea un nuevo Espacio dentro de un Espacio de Trabajo.
- Requiere: team_id (ID del Espacio de Trabajo), name.
- Opcional: multiple_assignees (booleano), features (objeto con indicadores de características como due_dates, time_tracking, etc.).
clickup_get_space: Recupera detalles para un Espacio específico.
- Requiere: space_id.
clickup_update_space: Actualiza un Espacio existente.
- Requiere: space_id.
- Opcional: name, color, private, admin_can_manage, archived, features.
clickup_delete_space: Elimina un Espacio.
- Requiere: space_id.

Gestión de Carpetas

clickup_get_folders: Recupera todas las Carpetas dentro de un Espacio dado.
- Requiere: space_id.
- Opcional: archived (booleano, el valor predeterminado es false).
clickup_create_folder: Crea una nueva Carpeta dentro de un Espacio.
- Requiere: space_id, name.
clickup_get_folder: Recupera detalles para una Carpeta específica.
- Requiere: folder_id.
clickup_update_folder: Actualiza una Carpeta existente.
- Requiere: folder_id, name.
clickup_delete_folder: Elimina una Carpeta.
- Requiere: folder_id.

Gestión de Campos Personalizados

clickup_get_custom_fields: Recupera todos los Campos Personalizados accesibles para una Lista dada.
- Requiere: list_id.
clickup_set_task_custom_field_value: Establece el valor de un Campo Personalizado en una tarea específica.
- Requiere: task_id, field_id, value.
- Opcional: value_options (objeto, por ejemplo, { "time": true } para campos de fecha).
clickup_remove_task_custom_field_value: Elimina/limpia el valor de un Campo Personalizado de una tarea específica.
- Requiere: task_id, field_id.

Gestión de Documentos

Nota: La API de ClickUp para Documentos (especialmente v2, con algunas operaciones que ahora usan v3) tiene limitaciones. El contenido se maneja principalmente como Markdown. El formato avanzado o los embeds complejos podrían no ser totalmente compatibles. La eliminación directa de documentos a través de la API no es actualmente compatible con el endpoint /docs de V3 de ClickUp; gestiona el ciclo de vida de los Documentos a través del archivado o la manipulación de páginas.

clickup_search_docs: Busca Documentos dentro de un Espacio de Trabajo (Equipo).
- Requiere: workspace_id.
- Opcional: query (cadena), include_archived (booleano).
clickup_create_doc: Crea un nuevo Documento.
- Requiere: workspace_id, name.
- Opcional: parent (objeto con id y type), visibility (cadena: "private", "workspace", "public"), create_page (booleano).
clickup_get_doc_pages: Recupera la lista de páginas dentro de un Documento específico.
- Requiere: doc_id.
clickup_create_doc_page: Crea una nueva página dentro de un Documento específico.
- Requiere: workspace_id, doc_id, name (título de la página).
- Opcional: content (Markdown), orderindex (número, aunque la API v3 podría no usarlo), parent_page_id (cadena), sub_title (cadena), content_format (cadena).
clickup_get_doc_page_content: Recupera el contenido (Markdown) de una página de Documento específica.
- Requiere: workspace_id, doc_id, page_id.
- Opcional: content_format (cadena).
clickup_edit_doc_page_content: Actualiza el contenido y/o el título de una página de Documento específica.
- Requiere: workspace_id, doc_id, page_id, content (Markdown).
- Opcional: title (cadena, se asigna al 'name' de la API), sub_title (cadena), content_edit_mode (cadena: "replace", "append", "prepend"), content_format (cadena).

Gestión de Vistas

clickup_get_views: Recupera todas las Vistas para un recurso padre dado (Equipo, Espacio, Carpeta o Lista).
- Requiere: parent_id (ID del recurso padre), parent_type (cadena: "team", "space", "folder" o "list").
clickup_create_view: Crea una nueva Vista dentro de un Equipo, Espacio, Carpeta o Lista.
- Requiere: parent_id, parent_type, name (cadena: nombre de la nueva Vista), type (cadena: tipo de la Vista, por ejemplo, "list", "board", "calendar", "gantt").
- Opcional: grouping, divide, sorting, filters, columns, team_sidebar, settings (objetos que definen configuraciones de vista).
clickup_get_view_details: Recupera detalles para una Vista específica.
- Requiere: view_id.
clickup_update_view: Actualiza una Vista existente.
- Requiere: view_id.
- Opcional: name (cadena), grouping, divide, sorting, filters, columns, team_sidebar, settings.
clickup_delete_view: Elimina una Vista.
- Requiere: view_id.
clickup_get_view_tasks: Recupera las tareas que pertenecen a una Vista específica.
- Requiere: view_id.
- Opcional: page (número: número de página basado en 0 para paginación).

Desarrollo

Clona el repositorio:

git clone <repository_url>
cd clickup-mcp-server

Instala las dependencias:
```
npm install
```

Crea un archivo .env en el directorio raíz y agrega tu CLICKUP_PERSONAL_TOKEN:

CLICKUP_PERSONAL_TOKEN=your_actual_personal_api_token_here
LOG_LEVEL=debug

Inicia en modo de desarrollo (Stdio): El servidor escuchará mensajes MCP en stdin/stdout.
```
npm run dev
```
Esto utiliza ts-node-dev para ejecutar src/index.ts.
Compila para producción:
```
npm run build
```
Esto compila TypeScript a dist/.
Ejecuta las pruebas:
```
npm test
```
Esto ejecuta las pruebas unitarias de Jest ubicadas en src/__tests__. Asegúrate de tener un archivo .env.test (consulta src/__tests__/setup.ts).

Pruebas con MCP Inspector

Puedes probar el servidor localmente usando el MCP Inspector:

Asegúrate de que tu CLICKUP_PERSONAL_TOKEN esté disponible. Puedes:
- Configurarlo en el entorno de tu shell antes de ejecutar el inspector.
- Configurarlo dentro de la interfaz de usuario de MCP Inspector si proporciona una opción para variables de entorno del servidor.
- Tenerlo en tu archivo local .env (ya que src/index.ts carga dotenv).
Ejecuta el Inspector con el servidor:
```
npx @modelcontextprotocol/inspector node --loader ts-node/esm src/index.ts
```
La interfaz de usuario del Inspector debería iniciarse, permitiéndote conectarte al servidor y llamar a sus herramientas.

Seguridad

Se autentica usando tu Token de API Personal de ClickUp. Mantén este token seguro y confidencial. Trátalo como una contraseña.
El servidor espera que el CLICKUP_PERSONAL_TOKEN se proporcione a través de una variable de entorno por parte del cliente MCP consumidor o del entorno de desarrollo.
El sistema de configuración incluye lógica para un ENCRYPTION_KEY y src/security.ts tiene funciones de cifrado, pero esto actualmente no se aplica al Token de API Personal por el ClickUpService.
Ningún dato sensible (como el token en sí) se registra por defecto con LOG_LEVEL=info. El nivel de depuración podría registrar más detalles.
La limitación de velocidad para las llamadas a la API de ClickUp se maneja registrando las solicitudes restantes (consulta ClickUpService).

Solución de Problemas

Problemas Comunes

Errores de Autenticación (401 de la API de ClickUp)
- Verifica que tu variable de entorno CLICKUP_PERSONAL_TOKEN esté correctamente configurada y sea accesible por el proceso del servidor.
- Asegúrate de que el token sea válido y no esté revocado en la configuración de tu ClickUp.
- Revisa los registros del servidor para ver mensajes de ClickUpService relacionados con la autenticación.
Limitación de Velocidad por la API de ClickUp
- El servidor registra información de limitación de velocidad de las respuestas de la API de ClickUp.
- Si los límites de velocidad se alcanzan con frecuencia, esto indica un uso elevado. El servidor en sí no implementa colas ni retrocesos complejos más allá de lo que axios podría hacer por defecto.
El Servidor No Se Inicia / Problemas de Conexión con MCP Inspector
- Asegúrate de que CLICKUP_PERSONAL_TOKEN esté configurado.
- Si usas npm run dev, verifica si hay errores de TypeScript o ts-node-dev en la consola.
- Si usas MCP Inspector con node --loader ts-node/esm src/index.ts, asegúrate de que ts-node y las dependencias del proyecto estén correctamente instaladas.
- Verifica si hay errores de consola de src/index.ts o ClickUpService.

Obtención de Registros del Servidor

Cuando se ejecuta a través de npm run dev o npm start, los registros van a la consola.
Si lo ejecuta un cliente MCP (como Claude para Desktop), los registros generalmente son gestionados por ese cliente. Para Claude para Desktop, los registros a menudo se pueden encontrar en:
- Windows: %USERPROFILE%\AppData\Local\Claude\Logs\mcp\<server_name_and_id>\<process_id>.log (la ruta puede variar ligeramente)
- macOS: ~/Library/Logs/Claude/mcp/<server_name_and_id>\<process_id>.log (la ruta puede variar ligeramente)

Soporte

Si encuentras útil este proyecto, considera invitarme a un café para apoyar el desarrollo y mantenimiento continuos.

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles