MCP Time Tracker

Rastreie o tempo faturável sem sair do chat.

GitHub
2

Documentação

Rastreie o tempo pelo Claude com um servidor gratuito, sem instalação

Destaque no Awesome MCP Servers - listagem no diretório | endpoint hospedado ao vivo, plano gratuito, sem cadastro.

Rastreie horas faturáveis sem sair do seu chat de IA. Diga "inicie um cronômetro no redesign da acme", continue trabalhando e depois peça "minhas horas desta semana por projeto" ou "linhas de fatura para acme em agosto". Ele mantém um cronômetro em execução, permite registrar tempo que você esqueceu de rastrear, aplica sua taxa horária por projeto e transforma o resultado em um relatório, um arquivo CSV ou um conjunto de itens de linha de fatura. Tudo é armazenado como JSON simples na sua própria máquina.

Criado por theluckystrike.

No Registro Oficial de MCP (io.github.theluckystrike/time-tracker-timesheet-billable-hours).

Listado no Índice de Produtos de IA - endpoint remoto ao vivo em mcp.zovo.one/s/time-tracker, plano gratuito, sem cadastro.

time-tracker demo

Rastreie horas faturáveis pelo chat e transforme-as diretamente em um relatório ou itens de linha de fatura, zero configuração, tudo local.

Instalação em 60 segundos

A publicação no npm para @theluckystrike/mcp-time-tracker está pendente. Até lá, o pacote de um clique .mcpb ou um clone+compilação é o caminho funcional, ambos verificados abaixo.

Um clique (.mcpb): baixe time-tracker.mcpb do lançamento mais recente e clique duas vezes nele no Claude Desktop: https://github.com/theluckystrike/mcp-servers/releases/latest

(claude_desktop_config.json):

{
  "mcpServers": {
    "time-tracker": {
      "command": "npx",
      "args": ["-y", "@theluckystrike/mcp-time-tracker"]
    }
  }
}

Claude Code:

claude mcp add time-tracker -- npx -y @theluckystrike/mcp-time-tracker

(.cursor/mcp.json):

{
  "mcpServers": {
    "time-tracker": {
      "command": "npx",
      "args": ["-y", "@theluckystrike/mcp-time-tracker"]
    }
  }
}

O formulário npx acima começa a funcionar no momento em que o pacote for publicado. Até lá, use o pacote .mcpb acima, ou compile a partir do código-fonte com exatamente estes três comandos:

git clone https://github.com/theluckystrike/mcp-servers.git && cd mcp-servers
npm install
npm run build -w packages/mcp-license -w servers/time-tracker

Em seguida, aponte o command do seu cliente para node com um argumento: o caminho absoluto para servers/time-tracker/dist/index.js.

Para executar no modo Pro, defina MCP_LICENSE_KEY no mesmo bloco de configuração, ou chame license_activate uma vez com sua chave.

Ferramentas

FerramentaO que ela faz
timer_startInicia um cronômetro em um projeto (tarefa, tags, taxa e moeda opcionais). Iniciar um novo para e registra o anterior. Um nome de projeto parcial que corresponda exatamente a um projeto existente é usado como esse projeto.
timer_stopPara o cronômetro em execução, grava a entrada e retorna a duração.
timer_statusO que está em execução, há quanto tempo e o total de hoje.
entry_addRegistra tempo que você já trabalhou (início mais fim ou minutos), com taxa e moeda opcionais: taxa "90 euros por hora" fatura como EUR 225,00 por 2,5 h. Nomes parciais de projeto são resolvidos como timer_start.
entry_listTabela compacta de entradas, filtrada por intervalo de datas e projeto.
entry_editAltera qualquer campo de uma entrada.
entry_deleteExclui uma entrada por id.
project_set_rateDefine a taxa horária e a moeda usadas para totais monetários (a moeda aceita códigos ou palavras: EUR, euros, libras, zl). apply_to_existing: true reavalia o tempo já registrado para esse projeto; adicione only_missing: true para tocar apenas em entradas sem taxa.
reportHoras e dinheiro de um período, opcionalmente agrupados por projeto, dia, tarefa ou tag; omita group_by para o total simples por moeda. Tabela, JSON ou CSV. Horas já faturadas são deixadas de fora; passe unbilled_only: false para a folha de ponto completa.
export_csvGrava entradas em um arquivo CSV e retorna o caminho.
invoice_summaryItens de linha prontos para fatura de um projeto: horas, taxa, valor, total, na moeda em que o tempo foi registrado. Uma linha por tarefa e taxa, para que nenhuma linha mostre uma taxa combinada que ninguém concordou. Retorna o entry_ids por trás das linhas e pula horas já faturadas (unbilled_only: false as inclui). Grátis nos últimos 7 dias, Pro para qualquer período do histórico completo.
entry_mark_billedCarimba as horas que foram para uma fatura com o número dela (ids de invoice_summary, ou project + from + to), para que report e invoice_summary parem de oferecê-las e as mesmas horas nunca sejam cobradas duas vezes.
license_statusGrátis ou Pro, e onde atualizar.
license_activateAtiva uma chave Pro (verificada offline).

Também expostos: o recurso timetracker://today (resumo de hoje) e o prompt daily_standup (escreve uma atualização de standup a partir do tempo rastreado de ontem e de hoje).

O que você pode dizer

Nenhum nome de ferramenta é necessário. Estas são as frases que foram realmente testadas contra o servidor; a coluna de ferramenta é o que respondeu a elas.

Você dizFerramenta
"Inicie um cronômetro para o projeto do site da Acme."timer_start
"Pare o cronômetro e me diga quanto tempo trabalhei."timer_stop
"O que está em execução agora e há quanto tempo?"timer_status
"Registre 2,5 horas ontem para Acme, revisão de design, a 90 euros por hora."entry_add
"Mostre minhas entradas da Acme desta semana."entry_list
"Essa última entrada deveria dizer refatoração de API, não revisão de design."entry_edit
"Exclua a entrada que acabei de registrar duas vezes."entry_delete
"Defina minha taxa para Acme em 90 EUR por hora."project_set_rate
"Quantas horas faturei este mês, agrupadas por projeto?"report
"Me dê as linhas de fatura para Acme em agosto."invoice_summary
"Faturei essas horas como INV-2026-0001."entry_mark_billed

Mais duas que valem a pena conhecer: "exporte meu tempo para um CSV para meu contador" (export_csv) e "escreva minha atualização de standup de ontem e hoje" (o prompt daily_standup).

Exemplo prático

Este é um transcript real da auditoria em docs/USER_VALUE_R2.md, números inalterados.

You: Log 2.5 hours yesterday for Acme, design review, at 90 euros an hour.

  entry_add { project: "Acme", ... }
  -> "Acme" resolved to the existing project "Acme website"
  -> rate "90 euros an hour" parsed as EUR 90.00/h

Assistant: Logged 2.50 h for Acme website - design review at EUR 90.00/h = EUR 225.00.

You: How much do I bill Acme this week? Give me invoice lines.

  invoice_summary { project: "Acme website", from: "2026-08-31", to: "2026-09-02" }

Assistant: Invoice summary - Acme website
  design review    2.50 h   EUR 90.00/h   EUR 225.00
  TOTAL            2.50 h                 EUR 225.00

Uma chamada cada. A taxa carrega sua moeda por todo o caminho: o relatório nunca imprime um "225" simples, e nunca vira "$225" por acidente.

Um segundo exemplo prático, o relatório semanal e o prompt daily_standup:

You: How many hours did I put into Acme this week, grouped by task?

  report { project: "Acme website", from: "2026-08-27", to: "2026-09-02", group_by: "task" }

Assistant: Acme website, 2026-08-27 to 2026-09-02
  design review   2.50 h   EUR 225.00
  TOTAL           2.50 h   EUR 225.00

You: Write my standup update.

  (prompt) daily_standup

Assistant: Yesterday: 2.50 h on Acme website (design review).
Today: nothing logged yet.

Fechamento de horas faturadas

Uma hora que foi faturada está encerrada. entry_mark_billed {ids, invoice_number} grava billed_at e billed_invoice nessas entradas; a partir daí, report e invoice_summary as pulam por padrão, para que o "faturar acme" do próximo mês não possa refaturar trabalho já pago. A folha de ponto completa ainda está lá: passe unbilled_only: false para qualquer uma delas. invoice_summary retorna o entry_ids que usou precisamente para que possam ser entregues diretamente a entry_mark_billed assim que a fatura existir.

report e invoice_summary respondem a perguntas sobrepostas de propósito: report é para "quanto tempo e dinheiro", agrupado como você quiser; invoice_summary é para "me dê as linhas que posso colocar em uma fatura", que é uma visão mais restrita, em formato de fatura, das mesmas entradas de um projeto.

Como ele armazena dados

Entradas, projetos e taxas vivem em um único arquivo JSON: ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/time-tracker/data.json.

Toda gravação (iniciar ou parar um cronômetro, adicionar, editar ou excluir uma entrada, definir uma taxa) acontece sob um arquivo de bloqueio consultivo em .../time-tracker/.lock, mantido durante todo o ciclo de carregar-mutar-salvar, para que duas chamadas sobrepostas não possam se intercalar e corromper o arquivo. A gravação em si escreve em um arquivo temporário e o renomeia para o lugar, para que uma falha ou um processo morto no meio da gravação deixe ou o arquivo antigo ou o novo, nunca um meio-escrito. Leituras (entry_list, report, timer_status, export_csv) não usam o bloqueio.

Para fazer backup dos seus dados, copie o único arquivo data.json (e .lock se presente, embora ele não contenha dados). Não há banco de dados e nenhum segundo arquivo oculto.

Se data.json estiver ilegível ou não for JSON válido, o servidor não trata isso como "sem dados ainda". Ele move o arquivo para o lado, byte por byte, como data.json.corrupt-<timestamp>, grava um marcador data.json.corrupt e faz todas as ferramentas, incluindo leituras, retornarem arquivo de dados corrompido; movido para ...; nada foi gravado. Restore a good data.json (a cópia em quarentena está bem ali) e exclua o arquivo de marcador para continuar. Nada é sobrescrito nesse meio tempo.

Datas, horários e taxas

  • Carimbos de data/hora sem deslocamento são seu horário local. 2026-09-02T09:00:00 significa 09:00 onde você está, não UTC. Passe um deslocamento explícito (2026-09-02T09:00:00+02:00) ou um Z final e ele será respeitado exatamente.
  • Limites somente de data cobrem dias locais inteiros. from: "2026-09-01" é 00:00:00 local no dia 1º e to: "2026-09-30" é 23:59:59.999 local no dia 30, então um mês relatado por datas inclui seu último dia. Carimbos de data/hora com hora são usados como fornecidos.
  • Entradas são recortadas para a janela. Uma entrada que começa antes de from ou termina depois de to conta para a parte dentro do período, não toda e não nenhuma.
  • Entradas são divididas à meia-noite local para agrupamento por dia. Trabalho das 23:30 às 01:30 é 0,5 h no primeiro dia e 1,5 h no seguinte, inclusive através de uma fronteira de mês. timer_status conta apenas a parte de uma entrada, ou do cronômetro em execução, que cai após a meia-noite de hoje.
  • Strings de taxa são analisadas, nunca adivinhadas. "1,200 USD" é 1200 (uma vírgula seguida de exatamente três dígitos é agrupamento de milhares), "12,50 EUR" é 12,50 (a forma decimal europeia inequívoca) e "1.200,50" é 1200,50. Qualquer coisa que possa significar uma coisa ou outra, como "1,2345", é recusada com um exemplo prático em vez de ser lida como o número errado.
  • Taxas são capturadas quando o tempo é registrado. entry_add e timer_stop armazenam a taxa horária efetiva e a moeda na entrada, e relatórios e faturas usam essa taxa armazenada. project_set_rate portanto se aplica apenas a entradas futuras; passe apply_to_existing: true para reavaliar o tempo já registrado para esse projeto. Isso recarimba TODA entrada do projeto, incluindo entradas que já carregam uma taxa, e a resposta diz quantas mudaram e o novo total do projeto. Adicione only_missing: true para tocar apenas em entradas que não capturaram taxa própria.
  • Linhas de tag se sobrepõem. Em group_by: "tag", uma entrada marcada com dev e meeting aparece em ambas as linhas; o total é calculado a partir das entradas uma vez, então nunca é a soma das linhas.

Limites e ressalvas honestas

  • Grátis entry_list, report, export_csv e invoice_summary só veem os últimos 7 dias. Cronômetros e entradas em si são ilimitados e nada é jamais excluído; a janela apenas estreita o que uma chamada gratuita pode ler de volta.
  • O plano gratuito suporta taxas horárias em 2 projetos; um terceiro projeto com taxa requer Pro.
  • Todo agrupamento report é gratuito, incluindo tag: o total de tag é uma correção de exatidão, não um recurso premium. group_by em si é opcional; omita-o para o total simples por moeda.
  • Apenas um cronômetro pode rodar por vez. Iniciar um segundo para e registra o primeiro; não há modo de cronômetro concorrente.
  • Não há lembrete ou detecção de inatividade: se você esquecer de parar um cronômetro, ele continua rodando até você pará-lo ou iniciar outro.

Solução de problemas

  • npx trava ou não encontra o pacote: a publicação no npm deste pacote está pendente. Use o pacote .mcpb ou o caminho de clone-e-compilação acima até que ela seja publicada.
  • Usando o pacote .mcpb: ele instala diretamente no Claude Desktop; não há caminho separado para configurar.
  • Usando o caminho de clone: o binário do servidor é servers/time-tracker/dist/index.js após npm run build. Aponte o command do seu cliente para node com esse caminho absoluto como único argumento.
  • Versão do Node: requer Node >= 18. Verifique com node -v.
  • Nada aparece / falhas silenciosas: este servidor grava logs apenas em stderr, nunca em stdout (stdout é reservado para o protocolo MCP). No Claude Desktop, verifique Configurações -> Desenvolvedor -> o arquivo de log do servidor; no Claude Code, execute com --mcp-debug ou verifique o terminal de onde você o iniciou.
  • Uma chave Pro não é reconhecida: execute license_status para ver o que o servidor acha que é seu nível, e confirme que MCP_LICENSE_KEY está definido no mesmo processo em que o cliente inicia (não apenas no seu shell).

Privacidade

Todos os dados permanecem locais: as entradas ficam em ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/time-tracker/data.json. O servidor não faz requisições de rede, não tem telemetria e não precisa de conta. As chaves de licença são assinaturas Ed25519 verificadas offline contra uma chave pública compilada no pacote; a ativação funciona sem conexão com a internet.

Combina com

FAQ

Sim. Todos os três falam MCP via stdio com o mesmo formato de configuração; as ferramentas e o arquivo de dados são idênticos independentemente do cliente.

Nada é excluído. A entrada permanece em data.json para sempre; ela simplesmente não aparecerá nos resultados de entry_list, report, export_csv ou invoice_summary até você ativar o Pro, que abre o histórico completo.

Sim. A moeda é definida por projeto (ou por entrada, substituindo o padrão do projeto) e cada total é agrupado por moeda; um relatório nunca soma EUR e USD juntos.

O servidor não bloqueia sobreposições; ele registra o que você informa. entry_edit permite corrigir um erro depois do ocorrido.

Não. Não há chamadas de rede em nenhum lugar deste servidor, inclusive para ativação de licença, que é verificada com uma chave pública local.

Licença

MIT

Um perfil de negócio para toda a suíte

Sua identidade é armazenada uma única vez, em ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/profile/business.json, e todos os servidores da suíte a leem: o emissor de faturas, o cabeçalho de docx, o emissor recorrente, a taxa de IVA padrão do expense-tracker, o fuso horário padrão do time-tracker e do timezone, e os cabeçalhos de currículo e contrato. Defina uma vez com business_set (invoice ou docx) — você nunca repete em nenhum outro lugar. Um endereço de e-mail só é obtido desse perfil ou de um argumento explícito; quando nenhum está armazenado, os documentos mostram [add: email] e a ferramenta informa isso em vez de deixar qualquer um improvisar um endereço.

Perguntas frequentes

Existe um servidor MCP gratuito de rastreamento de tempo?

Sim. O servidor time-tracker em mcp.zovo.one é um servidor MCP gratuito de rastreamento de tempo sem instalação: inicie e pare cronômetros no chat, mantenha totais por cliente e gere relatórios semanais. Diferente de rastreadores SaaS (WebWork, TrackingTime), ele não precisa de conta — cole a URL hospedada e pronto.

Como rastreio tempo pelo Claude?

Conecte https://mcp.zovo.one/mcp/time-tracker (URL tokenizada de mcp.zovo.one/mcp/connect) e diga: 'Inicie um cronômetro para o projeto Acme.' Pare-o mais tarde da mesma forma; resumos semanais estão a um pedido de distância.

Use estes documentos como um servidor MCP

Qualquer cliente MCP (Claude, Cursor, Windsurf, VS Code) pode ler a documentação deste repositório diretamente via GitMCP — sem instalação: