mcp-time-tracker

Rastreie horas em projetos com temporizadores de iniciar/parar, totais diários e exportação de folha de ponto — tudo executado diretamente do Claude ou de qualquer cliente MCP.

GitHubExperimente este MCPPatrocinado

Documentação

Rastreie o tempo a partir do Claude com um servidor gratuito, sem instalação

Servidor MCP para rastreamento de tempo: planilhas de horas, uma planilha de horas e um rastreador de horas faturáveis. Rastreie horas faturáveis sem sair do chat.

Funciona com Claude Desktop, Claude Code, Cursor e qualquer cliente do Model Context Protocol. Roda na sua própria máquina, ou hospedado sem instalação.

Página do produto: https://mcp.zovo.one/s/time-tracker — o que ele faz, as ferramentas que expõe e um endpoint de token ao vivo.

Instalação

Hospedado, nada para instalar. Obtenha um token em https://mcp.zovo.one/mcp/connect (a página de conexão) ou https://mcp.zovo.one/mcp/token (o mesmo token como JSON); um token anônimo gratuito é emitido na hora e uma chave Pro funciona da mesma forma. Em seguida, aponte um cliente MCP para https://mcp.zovo.one/mcp/time-tracker via streamable-http e envie o token como Authorization: Bearer <token>.

Se o seu cliente não puder definir cabeçalhos, coloque o token no caminho: https://mcp.zovo.one/mcp/time-tracker/t/<token>. Ambas as formas funcionam. A URL simples sem token responde 401 em tools/call, então o token não é opcional.

Claude Desktop, um clique. Baixe time-tracker.mcpb do último lançamento e clique duas vezes nele.

A partir do código-fonte. O espelho é autossuficiente: cada dependência @theluckystrike/* é fornecida, então um clone novo compila sem configuração extra.

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

Em seguida, aponte seu cliente para o ponto de entrada compilado:

{
  "mcpServers": {
    "time-tracker": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-time-tracker/dist/index.js"]
    }
  }
}

@theluckystrike/mcp-time-tracker ainda não está publicado no npm, então um comando npx -y @theluckystrike/mcp-time-tracker falhará. Os três caminhos acima são os que funcionam e cada um é exercitado pelo CI.

Espelho somente leitura de mcp-servers/servers/time-tracker. Veja MIRROR.md.

Apresentado no Awesome MCP Servers — listagem de diretório | endpoint hospedado ao vivo, nível 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 esta semana por projeto" ou "linhas de fatura para acme em agosto". Ele mantém um cronômetro em execução, permite que você registre o tempo que 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.

Construído por theluckystrike.

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

Listado no AI Product Index — endpoint remoto ao vivo em mcp.zovo.one/s/time-tracker, nível gratuito, sem cadastro.

Rastreie horas faturáveis a partir do 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 que funciona, ambos verificados abaixo.

Um clique (.mcpb): baixe time-tracker.mcpb do último lançamento 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 é 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

Ferramenta	O que ela faz
`timer_start`	Inicia um cronômetro em um projeto (tarefa opcional, tags, taxa, moeda). Iniciar um novo para e registra o antigo. Um nome de projeto parcial que corresponde exatamente a um projeto existente é usado como esse projeto.
`timer_stop`	Para o cronômetro em execução, grava a entrada, retorna a duração.
`timer_status`	O que está em execução, por quanto tempo e o total de hoje.
`entry_add`	Registra o tempo que você já trabalhou (início mais fim ou minutos), com taxa e moeda opcionais: taxa "90 euros por hora" cobra EUR 225,00 por 2,5 h. Nomes de projeto parciais resolvem como `timer_start`.
`entry_list`	Tabela compacta de entradas, filtrada por intervalo de datas e projeto.
`entry_edit`	Altera qualquer campo de uma entrada.
`entry_delete`	Exclui uma entrada por id.
`project_set_rate`	Define 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` re-classifica o tempo já registrado para esse projeto; adicione `only_missing: true` para tocar apenas entradas sem taxa.
`report`	Horas e dinheiro para 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 planilha completa.
`export_csv`	Grava entradas em um arquivo CSV e retorna o caminho.
`invoice_summary`	Itens de linha prontos para fatura para um projeto: horas, taxa, valor, total, na moeda em que o tempo foi registrado. Uma linha por tarefa e taxa, então nenhuma linha mostra 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 para os últimos 7 dias, Pro para qualquer período do histórico completo.
`entry_mark_billed`	Carimba as horas que foram para uma fatura com seu número (`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_status`	Grátis ou Pro, e onde atualizar.
`license_activate`	Ativa 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 as respondeu.

Você diz	Ferramenta
"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 por 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 para esta 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 cobrei 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

Esta é uma transcrição 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 se transforma em "$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á concluída. entry_mark_billed {ids, invoice_number} escreve billed_at e billed_invoice nessas entradas; a partir de então, report e invoice_summary as pulam por padrão, então o "faturar Acme" do próximo mês não pode re-cobrar trabalho já pago. A planilha inteira 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 uma vez que a fatura exista.

report e invoice_summary respondem perguntas sobrepostas de propósito: report é para "quanto tempo e dinheiro", agrupado da forma que você quiser; invoice_summary é para "me dê as linhas que posso colocar em uma fatura", que é uma visão mais estreita, em formato de fatura, das mesmas entradas para 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.

Cada 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, então duas chamadas sobrepostas não podem se intercalar e corromper o arquivo. A própria gravação escreve em um arquivo temporário e o renomeia para o lugar, então uma falha ou um processo morto no meio da gravação deixa 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 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>, escreve um marcador data.json.corrupt e faz todas as ferramentas, incluindo leituras, retornarem data file is corrupt; moved to ...; nothing was written. 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á honrado 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 à 01:30 é 0,5 h no primeiro dia e 1,5 h no próximo, 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 das duas coisas, 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 re-classificar o tempo já registrado para esse projeto. Isso re-carimba TODAS as entradas 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 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

Usuários gratuitos entry_list, report, export_csv e invoice_summary veem apenas os últimos 7 dias. Os timers e as entradas em si são ilimitados e nada é excluído; a janela apenas limita o que uma chamada gratuita pode ler de volta.
O plano gratuito suporta taxas horárias em 2 projetos; um terceiro projeto com taxa exige o Pro.
Cada agrupamento report é gratuito, incluindo a tag: o total por tag é uma correção de precisão, não um recurso premium. O group_by em si é opcional; omita-o para o total simples por moeda.
Apenas um timer pode rodar por vez. Iniciar um segundo para e registra o primeiro; não existe modo de timers concorrentes.
Não há lembrete ou detecção de inatividade: se você esquecer de parar um timer, 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 npm deste pacote está pendente. Use o pacote .mcpb ou o caminho de clonar e compilar acima até que ele seja publicado.
Usando o pacote .mcpb: ele instala diretamente no Claude Desktop; não há um caminho separado para configurar.
Usando o caminho de clonagem: 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 do seu nível, e confirme que MCP_LICENSE_KEY está definido no mesmo processo 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

mcp-invoice, transforme a saída de invoice_summary diretamente em uma fatura PDF numerada.
mcp-spreadsheet, exporte um CSV com export_csv e consulte ou reformate-o.
mcp-price-tracker, se você também compra itens para o cliente, acompanhe esses preços.
office-suite, todos os servidores irmãos em uma única instalação, uma única entrada de configuração.
Guia: Rastreie horas faturáveis no Claude Code e Cursor

Perguntas frequentes

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 apenas 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. O entry_edit permite corrigir um erro depois do fato.

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

Licença

MIT

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

Sua identidade é armazenada uma vez, em ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/profile/business.json, e cada servidor da suíte a lê: 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-a uma vez com business_set (invoice ou docx) — você nunca a repete em 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 alguém 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 timers no chat, mantenha totais por cliente e gere relatórios semanais. Ao contrário de rastreadores SaaS (WebWork, TrackingTime), ele não precisa de conta — cole a URL hospedada e comece.

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 timer para o projeto Acme.' Pare-o mais tarde da mesma forma; resumos semanais estão a um pedido de distância.

Use estas documentações 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:

URL MCP das documentações: https://gitmcp.io/theluckystrike/mcp-time-tracker