ComposioHQ/Toggl-Automation

Automação Toggl

Automatize suas operações de controle de tempo no Toggl Track diretamente do Claude Code. Registre horas, gerencie projetos e clientes, organize com tags e controle espaços de trabalho — tudo sem sair do terminal.

Documentação do toolkit: composio.dev/toolkits/toggl

---

Configuração

1. Adicione o servidor MCP Rube à configuração do Claude Code com a URL: https://rube.app/mcp
2. Quando solicitado, autentique sua conta Toggl Track através do link de conexão fornecido
3. Comece a automatizar seus fluxos de controle de tempo com linguagem natural

---

Fluxos de Trabalho Principais

1. Criar e Parar Registros de Tempo

Registre horas com associação a projetos, tarefas e tags, ou inicie/pare temporizadores.

Ferramentas: TOGGL_CREATE_TIME_ENTRY, TOGGL_PATCH_STOP_TIME_ENTRY

Inicie um registro de tempo no workspace 123456 para o projeto 78910 com as tags "reunião" e "design" e descrição "Sessão de revisão de design"

Parâmetros principais para TOGGL_CREATE_TIME_ENTRY:

• workspace_id (obrigatório) — workspace alvo
• created_with (obrigatório) — nome do aplicativo cliente (ex.: "api_client")
• start (obrigatório) — timestamp ISO 8601
• stop — timestamp ISO 8601 de término; omita para deixar o registro em execução
• duration — duração em segundos; omita para registros em execução
• project_id — associar a um projeto
• task_id — associar a uma tarefa
• tags — array de strings com nomes de tags (não IDs)
• description — descrição do trabalho
• billable — status de faturamento

Parâmetros principais para TOGGL_PATCH_STOP_TIME_ENTRY:

• workspace_id (obrigatório) e time_entry_id (obrigatório)

2. Gerenciar Projetos

Crie novos projetos e liste os existentes com detalhes do cliente e paginação.

Ferramentas: TOGGL_CREATE_PROJECT, TOGGL_GET_PROJECTS, TOGGL_GET_PROJECT_DETAILS

Crie um projeto privado faturável chamado "Campanha de Marketing Q1" no workspace 123456 para o cliente 78910

Parâmetros principais para TOGGL_CREATE_PROJECT:

• workspace_id (obrigatório) e name (obrigatório)
• client_id, billable, is_private, active, color
• estimated_hours, rate, fixed_fee, currency (recursos premium)

Parâmetros principais para TOGGL_GET_PROJECTS:

• workspace_id (obrigatório)
• page / page_size (1-200) para paginação
• since / until — timestamps Unix para filtro de modificação (apenas últimos 3 meses)
• clients: true para incluir detalhes completos do cliente

3. Gerenciar Clientes

Crie e liste clientes em um workspace.

Ferramentas: TOGGL_CREATE_CLIENT, TOGGL_GET_LIST_CLIENTS

Liste todos os clientes ativos no workspace 123456 e depois crie um novo cliente chamado "Acme Corp"

• TOGGL_CREATE_CLIENT requer workspace_id e name; aceita notes, external_reference
• TOGGL_GET_LIST_CLIENTS requer workspace_id; suporta status ("active", "archived", "both") e name (pesquisa insensível a maiúsculas/minúsculas)

4. Tags e Preferências do Workspace

Recupere tags para categorização e verifique as configurações do workspace.

Ferramentas: TOGGL_GET_TAGS, TOGGL_GET_WORKSPACE_PREFERENCES

Mostre todas as tags do workspace 123456 e as preferências do workspace

• TOGGL_GET_TAGS requer workspace_id; retorna IDs e nomes das tags
• TOGGL_GET_WORKSPACE_PREFERENCES requer workspace_id; retorna plano de preços e configurações de exibição

5. Descoberta de Workspaces

Liste todos os workspaces aos quais o usuário autenticado pertence.

Ferramenta: TOGGL_GET_USER_WORKSPACES

A quais workspaces Toggl tenho acesso?

• Nenhum parâmetro necessário
• Retorna todos os workspaces com IDs, nomes e metadados
• Use isso primeiro para descobrir os IDs dos workspaces para outras operações

6. Visibilidade de Projetos do Usuário

Liste projetos visíveis ao usuário autenticado.

Ferramenta: TOGGL_GET_USER_PROJECTS

Mostre todos os projetos que posso ver em meus workspaces

• Retorna projetos aos quais o usuário autenticado tem acesso
• Use em conjunto com TOGGL_GET_PROJECTS para visualizações no escopo do workspace

---

Armadilhas Conhecidas

• Tags usam nomes, não IDs: TOGGL_CREATE_TIME_ENTRY aceita nomes de tags como strings no array tags, ao contrário de muitas APIs que usam IDs. Use TOGGL_GET_TAGS para verificar os nomes de tags disponíveis.
• created_with é obrigatório: Todo registro de tempo deve incluir created_with (ex.: "api_client"). A falta deste campo causa falhas silenciosas.
• A duração está em segundos: O parâmetro duration nos registros de tempo está em segundos, não em horas. 1 hora = 3600 segundos.
• Restrição de timestamp since: O filtro since no TOGGL_GET_PROJECTS permite apenas timestamps dentro dos últimos 3 meses. Consultas mais antigas serão rejeitadas.
• Recursos premium bloqueados: Cores personalizadas, modelos, taxas fixas e tarifas por hora em projetos exigem um plano Toggl premium. Contas não premium receberão erros ao usar esses campos.
• Workspace ID necessário em toda parte: Quase todas as ferramentas Toggl exigem workspace_id. Sempre chame TOGGL_GET_USER_WORKSPACES primeiro para resolvê-lo.

---

Referência Rápida

Slug da Ferramenta	Descrição
TOGGL_CREATE_TIME_ENTRY	Criar um registro de tempo ou temporizador em execução (requer workspace_id, created_with, start)
TOGGL_PATCH_STOP_TIME_ENTRY	Parar um registro de tempo em execução (requer workspace_id, time_entry_id)
TOGGL_GET_PROJECTS	Listar projetos em um workspace com paginação
TOGGL_GET_PROJECT_DETAILS	Obter detalhes de um projeto específico
TOGGL_CREATE_PROJECT	Criar um novo projeto (requer workspace_id, name)
TOGGL_GET_LIST_CLIENTS	Listar clientes com filtros de status/nome (requer workspace_id)
TOGGL_CREATE_CLIENT	Criar um novo cliente (requer workspace_id, name)
TOGGL_GET_TAGS	Listar todas as tags em um workspace (requer workspace_id)
TOGGL_GET_WORKSPACE_PREFERENCES	Obter configurações do workspace (requer workspace_id)
TOGGL_GET_USER_WORKSPACES	Listar todos os workspaces do usuário autenticado
TOGGL_GET_USER_PROJECTS	Listar projetos visíveis ao usuário autenticado

---

Desenvolvido por Composio