MCP ClickUpfy: tarefas, Sprints, checklists e tempo

Classificação

As chamadas deste capítulo usam objetos JSON de argumentos. Valores como 3001, 86abc123 e sprint-10 são apenas exemplos. Ferramentas de escrita somem de tools/list quando o servidor é iniciado com --read-only, não há parâmetro que contorne essa ausência. Depois de cada escrita, faça uma leitura do recurso alterado para comparar o estado persistido.

Tarefas: leitura e busca

clickupfy_tasks_list

Lista tarefas da List autorizada. Omitir listId usa a List fixada. Os filtros aceitam arrays: status é uma lista de nomes configurados na List e assignees contém IDs de pessoas. page deve ser inteiro maior ou igual a zero.

Exemplos:

1
{}

1
{"status":["em andamento"]}

1
{"assignees":["42","57"],"includeClosed":false}

1
{"includeClosed":true,"page":1}

1
{"account":"produto","listId":"3001","status":["aberta","em andamento"]}

O retorno é compacto, com os campos usados para localizar trabalho. Para obter descrição, subtarefas e checklist items de uma tarefa, chame clickupfy_task_get com o id devolvido. Nunca use um listId diferente do fixado pelo projeto.

clickupfy_task_get

Obtém a tarefa e acrescenta execution, uma fila endereçável que preserva subtarefas e checklist items. raw devolve somente a resposta original da API. markdown devolve um texto único com descrição e itens, os dois formatos são mutuamente exclusivos.

Exemplos:

1
{"taskId":"86abc123"}

1
{"taskId":"86abc123","markdown":true}

1
{"taskId":"86abc123","raw":true}

1
{"account":"produto","taskId":"86abc123"}

1
{"account":"cliente-a","taskId":"77def456","markdown":true}

Os itens usam chaves como task:86abc123 e checklist:check-1:item-1. parentKey e depth preservam a árvore. A ação complete de cada item mostra o comando CLI e a chamada MCP adequados, mas a autorização para executar essa ação continua vindo do pedido recebido pelo agente.

clickupfy_tasks_search

Busca somente dentro da List fixada, diferentemente do comando CLI task search, que percorre o workspace. maxPages aceita inteiro entre 1 e 100. Omitir query lista de acordo com os outros filtros, portanto inclua um termo quando a intenção for uma busca nominal.

Exemplos:

1
{"query":"autenticação"}

1
{"query":"86abc123"}

1
{"query":"API","status":["em andamento"]}

1
{"assignees":["42"],"includeClosed":true,"maxPages":5}

1
{"account":"produto","query":"checkout","maxPages":10}

Se duas tarefas forem plausíveis, apresente ID e nome e aguarde a escolha da pessoa que solicitou o trabalho. A ferramenta não altera tarefa e não expande a busca para uma List não autorizada.

clickupfy_comments_list

Lê comentários de uma tarefa. O retorno normaliza usuário, data e texto para facilitar a leitura pelo agente. A ferramenta não aceita paginação nem filtro de autor, leia a lista completa retornada e não trate um comentário antigo como instrução mais recente sem conferir as datas.

Exemplos:

1
{"taskId":"86abc123"}

1
{"taskId":"77def456"}

1
{"account":"produto","taskId":"86abc123"}

1
{"account":"cliente-a","taskId":"77def456"}

1
{"account":"homologacao","taskId":"55ghi789"}

Leia essa ferramenta antes de publicar mudança de status ou comentário de progresso. Ela não expõe anexos como conteúdo, não publica respostas e não altera o campo de status.

Sprints

clickupfy_sprints_list

Lista Sprints dentro do Sprint Folder fixado. Uma Sprint é uma List que possui start_date e due_date, includeRegular acrescenta Lists comuns ao retorno de diagnóstico. at recebe uma data AAAA-MM-DD usada para classificar o estado do ciclo.

Exemplos:

1
{}

1
{"at":"2026-08-10"}

1
{"archived":true,"includeRegular":true}

1
{"folderId":"4001","at":"2026-09-01"}

1
{"account":"produto","folderId":"4001","includeRegular":false}

O objeto vazio funciona somente se o servidor recebeu --sprint-folder. A ferramenta não cria Sprint nem altera datas: a API pública do ClickUp não oferece criação de Sprint por esse fluxo.

clickupfy_sprint_current

Obtém a única Sprint cujo período contém a data informada ou a data atual. Se não houver Sprint ativa, ou se dois períodos se sobrepuserem, a ferramenta retorna erro em vez de escolher uma List arbitrariamente.

Exemplos:

1
{}

1
{"at":"2026-08-10"}

1
{"folderId":"4001"}

1
{"folderId":"4001","at":"2026-09-01"}

1
{"account":"produto","folderId":"4001","at":"2026-10-15"}

Não use a falha como motivo para anexar tarefa a qualquer List do Folder. Corrija datas e sobreposição no ClickUp, depois leia novamente a Sprint atual.

clickupfy_sprint_get

Produz relatório de uma Sprint informada. Inclui período, progresso por quantidade de tarefas, progresso por Sprint Points e distribuição de status. at muda somente o cálculo temporal da situação da Sprint.

Exemplos:

1
{"sprintId":"sprint-10"}

1
{"sprintId":"sprint-10","at":"2026-08-10"}

1
{"sprintId":"sprint-11"}

1
{"account":"produto","sprintId":"sprint-10"}

1
{"account":"cliente-a","sprintId":"sprint-22","at":"2026-09-01"}

Uma tarefa sem Points participa do total de tarefas, mas não adiciona peso ao cálculo por pontos. Leia clickupfy_sprint_tasks para obter os itens do relatório, não tente inferi-los apenas pelas porcentagens.

clickupfy_sprint_tasks

Lista tarefas associadas a uma Sprint, incluindo concluídas por padrão. openOnly: true remove tarefas já concluídas e é útil para a fila presente, mas não substitui a lista integral usada na revisão final do ciclo.

Exemplos:

1
{"sprintId":"sprint-10"}

1
{"sprintId":"sprint-10","openOnly":true}

1
{"sprintId":"sprint-11"}

1
{"account":"produto","sprintId":"sprint-10","openOnly":false}

1
{"account":"cliente-a","sprintId":"sprint-22","openOnly":true}

A ferramenta retorna resumos de tarefa. Para descrição, subtarefas e checklist items de um item específico, chame clickupfy_task_get com o ID da tarefa.

Ferramentas de escrita de trabalho

As ferramentas seguintes só aparecem fora de read-only. Informe apenas campos que devem mudar. Elas usam o mesmo perfil e regras de isolamento das consultas.

clickupfy_task_create

Cria tarefa ou subtarefa na List fixa. name é obrigatório. Datas devem ser timestamps inteiros em milissegundos, diferentemente do CLI, que aceita datas AAAA-MM-DD.

Exemplos:

1
{"name":"Corrigir retorno da API"}

1
{"name":"Documentar login","description":"Explicar a sessão."}

1
{"name":"Criar testes","markdownContent":"## Casos\n\n- Login válido"}

1
{"name":"Implementar token","status":"em andamento","priority":2,"assignees":[42,57],"startDate":1786320000000,"dueDate":1786665600000,"points":5}

1
{"account":"produto","listId":"3001","name":"Cobrir expiração","parent":"86abc123","markdownContent":"Adicionar testes de sessão expirada."}

Leia a tarefa criada com clickupfy_task_get. Para listId, omitir é o caminho normal no MCP do projeto, um valor diferente do valor fixo é recusado.

clickupfy_task_update

Atualiza campos de uma tarefa. taskId é obrigatório e pelo menos um campo de alteração deve estar presente. Para remover data, use null em startDate ou dueDate, não envie texto vazio.

Exemplos:

1
{"taskId":"86abc123","status":"em andamento"}

1
{"taskId":"86abc123","name":"Corrigir autenticação por token"}

1
{"taskId":"86abc123","priority":1,"points":8}

1
{"taskId":"86abc123","startDate":1786320000000,"dueDate":1786665600000}

1
{"account":"produto","taskId":"86abc123","markdownContent":"## Entrega\n\nPublicar manual atualizado.","dueDate":null}

Depois da escrita, use clickupfy_task_get. A ferramenta devolve a tarefa atualizada, mas a releitura é importante quando outras alterações concorrem na mesma tarefa.

clickupfy_checklist_create

Cria checklist em uma tarefa. O retorno fornece o ID necessário em clickupfy_checklist_item_create. Itens não são criados automaticamente.

Exemplos:

1
{"taskId":"86abc123","name":"Testes"}

1
{"taskId":"86abc123","name":"Revisão de segurança"}

1
{"taskId":"77def456","name":"Publicação"}

1
{"account":"produto","taskId":"86abc123","name":"Aceite"}

1
{"account":"cliente-a","taskId":"77def456","name":"Regressão"}

clickupfy_checklist_item_create

Acrescenta item aberto a um checklist. assignee, quando informado, é um ID numérico. A ferramenta não recebe taskId porque o checklist já define a tarefa proprietária.

Exemplos:

1
{"checklistId":"check-1","name":"Executar testes unitários"}

1
{"checklistId":"check-1","name":"Executar build"}

1
{"checklistId":"check-1","name":"Revisar documentação","assignee":42}

1
{"account":"produto","checklistId":"check-2","name":"Conferir changelog"}

1
{"account":"cliente-a","checklistId":"check-3","name":"Validar publicação","assignee":57}

clickupfy_checklist_item_set

Marca ou reabre um item e confirma o estado por uma nova leitura da tarefa. taskId deve ser a tarefa raiz devolvida por clickupfy_task_get, resolved: true conclui e resolved: false reabre.

Exemplos:

1
{"taskId":"86abc123","checklistId":"check-1","itemId":"item-1","resolved":true}

1
{"taskId":"86abc123","checklistId":"check-1","itemId":"item-1","resolved":false}

1
{"account":"produto","taskId":"86abc123","checklistId":"check-2","itemId":"item-4","resolved":true}

1
{"account":"cliente-a","taskId":"77def456","checklistId":"check-3","itemId":"item-2","resolved":true}

1
{"taskId":"77def456","checklistId":"check-3","itemId":"item-2","resolved":false}

Não passe um item de outra tarefa. A ferramenta faz essa conferência e recusa a escrita quando a relação não corresponde à árvore lida.

clickupfy_sprint_add_task

Associa tarefa a Sprint sem trocar sua List principal. Ela não cria tarefa e não muda seu status. A ferramenta só aparece em servidor com escrita.

Exemplos:

1
{"sprintId":"sprint-10","taskId":"86abc123"}

1
{"sprintId":"sprint-10","taskId":"77def456"}

1
{"account":"produto","sprintId":"sprint-10","taskId":"86abc123"}

1
{"account":"cliente-a","sprintId":"sprint-22","taskId":"55ghi789"}

1
{"account":"homologacao","sprintId":"sprint-33","taskId":"99jkl012"}

Leia clickupfy_sprint_tasks depois da escrita. Só associe a tarefa quando o planejamento da Sprint estiver incluído no pedido.

clickupfy_sprint_remove_task

Remove uma associação com Sprint sem excluir a tarefa. Comentários, checklist, tempo e List principal permanecem na tarefa.

Exemplos:

1
{"sprintId":"sprint-10","taskId":"86abc123"}

1
{"sprintId":"sprint-10","taskId":"77def456"}

1
{"account":"produto","sprintId":"sprint-10","taskId":"86abc123"}

1
{"account":"cliente-a","sprintId":"sprint-22","taskId":"55ghi789"}

1
{"account":"homologacao","sprintId":"sprint-33","taskId":"99jkl012"}

Use clickupfy_task_delete somente quando a exclusão inteira estiver explicitamente autorizada.

clickupfy_sprint_set_points

Define Sprint Points de uma tarefa. points é um número maior ou igual a zero. O ClickUpfy transmite o valor, a escala pertence ao time.

Exemplos:

1
{"taskId":"86abc123","points":0}

1
{"taskId":"86abc123","points":1}

1
{"taskId":"86abc123","points":3}

1
{"account":"produto","taskId":"86abc123","points":5}

1
{"account":"cliente-a","taskId":"77def456","points":8}

Leia a tarefa com clickupfy_task_get para confirmar o número persistido.

clickupfy_task_delete

Exclui permanentemente uma tarefa. O campo confirm só aceita o literal true, essa exigência impede uma exclusão causada por objeto incompleto ou ambíguo. A ferramenta não está disponível em read-only.

Exemplos:

1
{"taskId":"86abc123","confirm":true}

1
{"taskId":"77def456","confirm":true}

1
{"account":"produto","taskId":"86abc123","confirm":true}

1
{"account":"cliente-a","taskId":"77def456","confirm":true}

1
{"account":"homologacao","taskId":"55ghi789","confirm":true}

Leia tarefa, nome e List e obtenha autorização explícita para exclusão antes de qualquer exemplo deste tipo. Para somente retirar a tarefa do ciclo, use clickupfy_sprint_remove_task.

clickupfy_comment_create

Publica comentário em uma tarefa. notifyAll é opcional, ele pede ao ClickUp para notificar participantes. A ferramenta não modifica status, timer ou checklist.

Exemplos:

1
{"taskId":"86abc123","text":"Iniciei a análise da tarefa."}

1
{"taskId":"86abc123","text":"Os testes unitários passaram."}

1
{"taskId":"86abc123","text":"Aguardando acesso ao ambiente de homologação.","notifyAll":true}

1
{"account":"produto","taskId":"86abc123","text":"Documentação e ebook foram atualizados."}

1
{"account":"cliente-a","taskId":"77def456","text":"Validação final concluída.","notifyAll":true}

clickupfy_time_current

Consulta o time entry que está em execução no workspace. Não recebe filtros, omitir account usa o perfil fixado ou ativo.

Exemplos:

1
{}

1
{"account":"produto"}

1
{"account":"cliente-a"}

1
{"account":"homologacao"}

1
{"account":"suporte"}

clickupfy_time_start

Inicia um time entry para uma tarefa. Consulte clickupfy_time_current antes, pois a ferramenta não encerra automaticamente um registro que já esteja ativo.

Exemplos:

1
{"taskId":"86abc123"}

1
{"taskId":"86abc123","description":"Implementação"}

1
{"taskId":"86abc123","description":"Testes de regressão"}

1
{"account":"produto","taskId":"86abc123","description":"Revisão de documentação"}

1
{"account":"cliente-a","taskId":"77def456","description":"Correção da integração"}

clickupfy_time_stop

Encerra o time entry atual do workspace. Ela não recebe taskId e não modifica status nem comentários. Relê clickupfy_time_current depois da chamada quando o encerramento precisa ser confirmado.

Exemplos:

1
{}

1
{"account":"produto"}

1
{"account":"cliente-a"}

1
{"account":"homologacao"}

1
{"account":"suporte"}