ClickUp MCP Server

Un servidor Model Context Protocol para ClickUp, construido alrededor de dos ideas:

Todo acepta nombres humanos. find(scope: "Cavalry/Findings", assignee: "me", due: "overdue") — sin IDs, sin recorrer el árbol para descubrirlos. Poner nombres que no se resuelven genera un error que enumera las opciones válidas, porque un resultado vacío yustificado es peor que un fallo.

Tú eliges lo que puede hacer. Cuatro perfiles de capacidad, aplicados en cada petición saliente. Dale a un agente sin supervisar el perfil agent y podrá crear tareas y comentarios, pero no podrá alterar ni borrar nada que ya exista.

18 herramientas, 354 pruebas. Versión 4.3.0 — consulta CHANGELOG.md. Un fork fuertemente renovado de nsxdavid/clickup-mcp-server.

Estado: 4.x es nueva. Ha pasado por cinco rondas adversariales de red-team, pero todavía no se ha ejecutado en producción. La línea anterior 3.x sigue incluida en este repositorio y sigue siendo la que usa el despliegue de referencia — ver Ejecutar 3.x.

Inicio rápido

Obtén un token en ClickUp → Settings → Apps → API Token (empieza por pk_). El espacio de trabajo se descubre automáticamente — no hay nada más que configurar.

Sin instalación:

{
  "mcpServers": {
    "clickup": {
      "command": "npx",
      "args": ["-y", "github:benthesoundguy/clickup-mcp-server"],
      "env": { "CLICKUP_API_TOKEN": "pk_your_token_here" }
    }
  }
}

O desde un clon, que es lo que quieres si piensas cambiar algo:

git clone https://github.com/benthesoundguy/clickup-mcp-server
cd clickup-mcp-server
npm install          # builds automatically
npm run check        # verifies the token and connects — do this before wiring up a client

{
  "mcpServers": {
    "clickup": {
      "command": "node",
      "args": ["/absolute/path/to/clickup-mcp-server/build/v4/index.js"],
      "env": { "CLICKUP_API_TOKEN": "pk_your_token_here" }
    }
  }
}

Dónde va el bloque de configuración

La forma anterior funciona tal cual en Claude Desktop, Claude Code, Cursor, Cline y Windsurf — todos usan la clave mcpServers. Dos clientes se diferencian:

• VS Code (.vscode/mcp.json) usa servers en lugar de mcpServers. La estructura interna es la misma. La configuración de Cursor copiada sin cambios de salvación es el error de configuración más habitual.

• Zed (settings.json) usa context_servers y anida el comando:

  { "context_servers": { "clickup": { "command": { "path": "node", "args": ["/path/to/build/v4/index.js"] } } } }

Claude Code puede saltarse el archivo por completo:

claude mcp add clickup --env CLICKUP_API_TOKEN=pk_... -- npx -y github:benthesoundguy/clickup-mcp-server

Poner el token en un archivo

Si prefieres no pegar el token en un cliente de configuración — las aplicaciones de escritorio reescriben esos archivos y pueden conservar una copia obsoleta — escriba un .env junto al bloque de instalación y omite la sección env por completo:

echo 'CLICKUP_API_TOKEN=pk_your_token_here' > .env

El servidor busca en <cwd>/.env, <install>/.env y <install>/../.env, en ese orden, e indica cuál usó al arrancar. El token del archivo tiene prioridad sobre el entorno, de modo que rotarlo en un solo lugar de verdad surte efecto. El resto de ajustes funciona al revés — el valor explícito de tu cliente siempre vence, así que un .env suelto jamás puede ampliar MCP_PROFILE. Pon MCP_STRICT_ENV=1 en un servidor descolocar toda la búsqueda.

Cuando algo no funciona

npm run check          # from a clone
node build/v4/index.js --check

Esto imprime toda la información que ha resuelto el servidor — qué .env ha encontrado y qué ha aplicado, si el token está presente y con laforma correcta, el perfil activo y el número de herramientas, el número de versión de Node y el sello de compilación — y luego realmente se conecta a ClickUp e informa de quién eres y de tu presupuesto de tasa de peticiones. Nunca imprime el token, por lo que es seguro copiar y pegar su salida en una incidencia.

Si el token falta, el servidor no muere en silencio en el modo stdio. Se pone en marcha, registra sus herramientas y cada llamada responde con cuál es el problema y cómo corregirlo, de modo que el problema aparece en tu conversación en lugar de un registro que tengas que buscar. (En modo HTTP sí sale con 1— un despliegue no atendido debe fallar de forma evidente.)

Related MCP server: ClickUp MCP Server

Capability profiles

Un solo binario, cuatro perfiles, seleccionados mediante MCP_PROFILE. Instala una vez y añade una entrada de cliente por perfil, habilitando los que signan juntos al agente.

El coste de esquema es lo que consumen las definitiones de herramientas en el contexto del modelo en cada petición, antes de que pase. Para comparar, 3.x cuenca ~18,600 tokens por 88 herramientas.

agent es el interesante. Puede añadir, pero nunca configurar ni destruir, por lo que lo peor que puede hacer un agente no atendido es crear basura que puedas eliminar. Esa garantía se aplica en tres capas, las únicas capas de control de seguridad:

1. Filtrado de herramientas — qué herramientas aparecen y por su (coste de contexto + selección de herramientas)

2. Filtrado de acciones — qué acciones anuncia una herramienta (coste de contexto + herramienta honesta)

3. Política de escritura — una lista de permitidos comprobada en cada petición saliente, implementaciones de subida ← la garantía

La capa 1 y 2 dependen de que cada herramienta esté etiquetada correctamente por cualquier contribuidor futuro. La capa 3 no depende: inspecciona la petición real cuando sale, si una herramienta mal etiquetada, una reescritura o un endpoint cualquier día no podrá ampliar un perfil. La suite de pruebas lo demuestra llamando a manejadores core de forma directa con un contexto agent — evitando por completo las capas 1 y 2 — y corroborando que nada llega a la conexión inalámbrica.

Las que parecen añadidos pero se excluyen de agent a propósito: añadir una etiqueta, establecer un campo no personalizado, y añadir una dependencia para modificar una tarea existente; crear un webhook para la transmisión de tus datos a un endpoint externo. Modo de solo añadir y seguridad no son la misma propiedad.

Por qué el predeterminado es core y no full

full da administración de miembros — invitar a un usuario consume un asiento de pago, y eliminar uno modifica el acceso de una persona real — además de webhooks, que envían datos del espacio de trabajo a externo. Nada de eso es para lo que se usa una conexión inicial. Y un predeterminado que nadie cambia debe ser el seguro. Pide la administración por nombre cuando la quieras; hasta entonces, la negativa te explicará exactamente cómo.

Archivos adjuntos y el sistema de archivos

attach lee un archivo de la máquina en que se ejecuta el servidor. Este es un recurso que la política de escritura no puede inspeccionar: examina URLs, pero la lectura de un archivo no usa URL — por lo que se regula de forma independiente con CLICKUP_ATTACH_ROOT:

• Configurado — Las lecturas se limitan a ese directorio. La contención se comprueba contra la ruta real del archivo, después de resolver .. y todos los enlaces simbólicos.

• Sin configurar — Los perfiles core y full pueden leer cualquier archivo que el proceso pueda. Con agent, attach no se ofrece en absoluto (12 herramientas en lugar de 13), porque no hay una raíz por defecto segura: el directorio de trabajo suele ser el del proyecto, que es donde está .env.

Una raíz configurada de forma incorrecta se limita al arranque, no se ignora— un límite que no está de forma silenciosa no está seguro.

Herramientas

Las herramientas o beren for (Re) se reduce no se ocultan: con read, comment solo muestra sus argumentos de lectura y checklist solo revela list, por lo que el esquema dice la verdad sobre lo que esta conexión puede hacer, en lugar de lanzar acciones que se rechazarían.

La regla que todo sigue

Nunca devolver una respuesta segura y falsa. ClickUp facilita no equivocarse, porque responde a las entradas erróneas con chorradas agradables:

Así que este servidor resuelve nombres y soporta la ambigüedad («Findings» coincide con cuatro listas esencialmente es un error que los resume los cuatro, nunca un capricho razonable); no se vacía cuando un valor de filtro no se resuelve; valida los enums del lado cliente contra lo que parte la lista realmente admite; confi millores las escrituras que no puede garantizar, leer la objecto de nuevo; y nunca sobre-intenta un recuento — una consulta que deja de lucrar en los pagos informa 100+ matches, y cualquier filtro en el cliente informa de cuánto ha escaneado realmente.

Los errores te dirán qué falló, por qué, y qué hacer a continuación, y siempre con lista válida de opciones.

Entorno variables

Modo remoto (Claude web + móvil, y cualquier cliente HTTP)

El servidor habla HTTP transmisible y acepta tres credenciales independientes. Cualquiera de ellas autentica una petición; están pensadas para coexistir, porque distintos clientes pueden presentar cosas distintas.

MCP_TRANSPORT=http MCP_AUTH_TOKEN=$(openssl rand -hex 24) \
MCP_PROFILE=core CLICKUP_API_TOKEN=... node build/v4/index.js

GET /health es una sonda sin autenticación que informa de la versión, el perfil activo, el número de herramientas y la raíz de adjuntos.

OAuth (lo que quieren los clientes alojados)

Este servidor no necesita ser un proveedor de OAuth, y no lo es. Desde la especificación MCP del 2025-06-18, un servidor MCP es un servidor de recursos: nombra el servidor de autorización en el que confía y valida los tokens que ese servidor emite. El inicio de sesión, el consentimiento y la emisión de tokens pertenecen a tu IdP — Cloudflare Access, WorkOS, Auth0, Descope, Stytch, Keycloak, cualquier cosa con descubrimiento OIDC.

MCP_TRANSPORT=http \
MCP_PUBLIC_URL=https://mcp.example.com \
MCP_OAUTH_ISSUER=https://your-idp.example.com \
CLICKUP_API_TOKEN=pk_... node build/v4/index.js

Esa es toda la configuración. El servidor entonces:

• sirve Metadatos de Recursos Protegidos RFC 9728 en /.well-known/oauth-protected-resource, nombrando a tu emisor, sin autenticación;

• responde a una petición sin autenticar con 401 y una cabecera WWW-Authenticate que apunta a ese documento, que es como un cliente descubre dónde iniciar sesión;

• descubre las claves de firma de tu emisor mediante /.well-known/openid-configuration (o RFC 8414), o usa MCP_OAUTH_JWKS_URL si lo defines;

• valida cada token: RS256 fijado, firma contra el JWKS del emisor, exp, nbf, iss y aud — el token debe nombrar a este servidor.

Esa última comprobación es la que importa. Sin ella, un token que tu IdP acuñó para algún otro servicio podría reproducirse aquí. Es por eso que MCP_PUBLIC_URL es obligatorio en lugar de inferido: la audiencia esperada nunca debe venir de la petición, porque la cabecera Host la define el llamante.

MCP_AUTH_TOKEN se vuelve opcional una vez que se configura un emisor: un despliegue solo-OAuth no necesita una contraseña compartida que nunca usa.

Nota sobre el Registro Dinámico de Clientes. La especificación del 2026-07-28 dejó de usar DCR en favor de los Documentos de Metadatos de ID de Cliente. Ese cambio recae en los servidores de autorización y los clientes; un servidor de recursos no se ve afectado en ningún caso, lo que es una buena razón para delegar en lugar de montar tu propio AS.

La advertencia del conector de claude.ai

La interfaz de conectores personalizados de Claude solo acepta campos OAuth — URL de autorización, URL de token, ID de cliente, secreto de cliente. No hay campo para un token portador estático ni una cabecera personalizada (#112, #411). Así que:

• Con OAuth configurado, conéctalo como un conector personalizado normal. Esa es la vía prevista.

• Sin OAuth, la única forma de entrar es el formato de token en la URL, /mcp/<token>, habilitado con MCP_ALLOW_TOKEN_IN_PATH=1. Funciona, pero pone una credencial en una URL donde los proxies la registran, por lo que el modo estricto la rechaza. Trátalo como un apaño, no como un despliegue.

Cloudflare Access (tercer modo de autenticación opcional)

Define CF_ACCESS_TEAM_DOMAIN y CF_ACCESS_AUD y el servidor valida la cabecera Cf-Access-Jwt-Assertion que Access pone en cada petición que reenvía: RS256 contra el JWKS del equipo, más exp, iss y aud. Ambos flujos de Access se validan por una sola vía — un inicio de sesión de navegador lleva email, un token de servicio lleva common_name.

Esto es defensa en profundidad. Una petición que llega al origen sin pasar por Access — una mala configuración del túnel, una segunda entrada, algo en la red del host — no puede hacerse pasar por un llamante autenticado por Access. Falla en cerrado: alg está fijado a RS256 (así que se rechazan alg: none y la confusión HS256), un JWKS inalcanzable deniega en lugar de eludir, y la URL del JWKS viene de la configuración, nunca del token.

La autenticación portadora sigue funcionando. Una petición se autoriza con un JWT de Access válido o un token portador válido, así que los agentes con capacidad de cabecera no necesitan cambios.

El origen no sirve /.well-known/oauth-* — con Managed OAuth habilitado, Access es el servidor de autorización y sirve el descubrimiento en el borde.

Modo estricto (MCP_STRICT_ENV=1)

La postura para un despliegue sin supervisión. Los secretos deben venir del entorno, el servidor nunca inventa ni persiste una credencial, y sale con 1 y un mensaje accionable en lugar de arrancar mal configurado. También rechaza el formato de token en la ruta de la URL, que deja la credencial en los registros de acceso del proxy.

Esto importa porque la búsqueda del archivo .env deliberadamente tiene prioridad sobre process.env — un host de escritorio reescribe su propio archivo de configuración desde la memoria al salir, así que el archivo tiene que ganar ahí. En un servidor esa prioridad es al revés: un .env suelto en el directorio de trabajo silenciosamente tendría prioridad sobre la unidad de systemd. El modo estricto desactiva la búsqueda.

Consulta deploy/DEPLOY.md para la receta completa: script de configuración de VPS, unidad de systemd endurecida, Cloudflare Tunnel y conexión con Claude.

Actualización desde 3.x

Los nombres de las herramientas son completamente distintos — 4.x es una reescritura, no un cambio de nombre. Cualquier cosa que tenga nombres de herramientas 3.x codificados (prompts guardados, instrucciones de agente, scripts) necesita actualizarse.

El mapeo es en su mayoría de muchos a uno:

No se trasladan: project_intelligence (los ocho informes de análisis locales) y reminders_create. La gestión de estados — crear, renombrar, reordenar estados — también está ausente; meta lee estados pero no los cambia. Si necesitas alguno de estos, ejecuta 3.x.

Ejecutar 3.x

3.x todavía se compila y se distribuye desde este repositorio:

npm run start:v3       # via the package script
node build/index.js    # the 3.x entry point directly

Apunta un cliente MCP a build/index.js en lugar de build/v4/index.js para seguir usándolo.

La unidad de systemd de referencia en deploy/ está deliberadamente fijada a 3.x, porque un servicio en ejecución no debería cambiar de versión principal porque un valor por defecto del paquete se haya movido debajo. Migra apuntando ExecStart a build/v4/index.js y definiendo MCP_PROFILE explícitamente.

Limitaciones conocidas de la API de ClickUp

No son errores aquí — la API realmente carece de estas funciones, y este servidor informa del límite en lugar de fingir que lo resuelve.

• Las tareas no se pueden mover entre listas. POST /list/{dest}/task/{id} devuelve 200 {} y no hace nada sin la ClickApp "Tasks in Multiple Lists"; PUT con list_id se ignora silenciosamente; /move devuelve 404. La ruta de movimiento de update vuelve a leer la tarea y falla estrepitosamente en lugar de informar de un movimiento que no sucedió.

• Los adjuntos no tienen un endpoint de lista — task los lee del objeto de la tarea. Las subidas son solo multipart, con un límite de 25 MB.

• Los Docs no se pueden renombrar ni eliminar, y las páginas no se pueden eliminar.

• Las definiciones de campos personalizados se pueden listar y crear, pero no editar ni eliminar.

• Los campos personalizados de fecha requieren milisegundos Unix; ClickUp rechaza YYYY-MM-DD para esos. Los due_date/start_date de las tareas aceptan ambos formatos y se convierten aquí.

• Los nombres de estados y etiquetas se almacenan en minúsculas; aquí la coincidencia no distingue entre mayúsculas y minúsculas en todos los casos.

• Las listas anulan constantemente los estados de su espacio, por lo que "qué estados son válidos" es una cuestión específica de cada lista. meta la responde por lista.

• ClickUp responde a un enum no válido con HTTP 500, por lo que los enums se validan en el cliente antes de enviarse.

• El límite de frecuencia es de aproximadamente 100 solicitudes/minuto por token, compartido entre todo lo que lo usa. whoami informa del presupuesto en tiempo real; el servidor se autorregula en función de las cabeceras x-ratelimit-*.

Receptor de webhooks (opcional)

Procesa eventos de webhook de ClickUp sin infraestructura externa:

WEBHOOK_PORT=3001 WEBHOOK_SECRET=your_secret node build/webhook-receiver/index.js

• Validación HMAC-SHA256 sobre el cuerpo en bruto de la solicitud; cuando hay un secreto configurado, las solicitudes sin firmar se rechazan

• Análisis estructurado de eventos: tipo, objeto, operación, cambios, usuario, marca de tiempo

• Reenvío opcional a una URL de callback (WEBHOOK_FORWARD_URL)

• http puro de Node.js, cero dependencias adicionales

Desarrollo

npm install
npm run build
npm test          # 354 tests, mocked HTTP — no token needed
npm run smoke     # live CRUD walk (needs CLICKUP_API_TOKEN; creates and
                  # deletes its own sandbox in your workspace)

Las notas de arquitectura para 4.x se encuentran en src/v4/README.md; la justificación de diseño y las mediciones están en V4-PLAN.md.

Depurar una corrección que "no funcionó"

Llama a whoami. Informa de la versión y el sello de la compilación en ejecución. Los hosts MCP crean su propio proceso de servidor al inicio de la sesión y lo mantienen, por lo que una recompilación no llega a una sesión ya en ejecución: si el sello es anterior a tu cambio, reinicia la aplicación host. Esto explicó varios informes de errores fantasma antes de que existiera la herramienta.

Licencia

MIT — consulta LICENSE. Fork de nsxdavid/clickup-mcp-server por David Whatley.