convez.ai
MCP ServerUtilidadesIntermediário
danielsimonjr

Time MCP — Servidor de Tempo, Timers e Alarmes

danielsimonjr/time-mcp

Timers, stopwatches e alarmes para Claude com suporte a timezones IANA

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP em TypeScript que fornece ferramentas de gerenciamento de tempo para Claude Code, incluindo consulta de horários em timezones, timers de contagem regressiva, cronômetros e alarmes com parsing em linguagem natural. Utiliza Luxon para cálculos de timezone/DST e chrono-node para interpretação de datas e horas conversacionais.

Instalação

$npx convez-ai danielsimonjr/time-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
v0.3.2
Issues abertas
0
Contribuidores
1

Casos de uso

  • Gerenciar múltiplos timers durante desenvolvimento ou debugging
  • Definir alarmes contextualizados em diferentes fusos horários
  • Contar tempo decorrido de tarefas com cronômetros reutilizáveis
  • Converter horários entre timezones com tratamento de DST

Veredito

Implementação sólida de um MCP server essencial para fluxos que requerem controle de tempo. Arquitetura sem daemons (status computado sob demanda) é adequada para integração com Claude Code, e suporte a notificações via hook é um diferencial prático. Codebase TypeScript bem estruturado e documentação clara.

README

A tradução para o português deste README ainda está na fila.

time-mcp

A TypeScript MCP server providing time, timezone, timer, stopwatch, and alarm tools for Claude Code. Built on @modelcontextprotocol/sdk, Luxon for timezone/DST, and chrono-node for natural-language alarm parsing.

Tools (14)

Time & Timezone (2)

ToolPurpose
get_current_timeCurrent time in any IANA timezone (defaults to system zone). Returns ISO datetime, HH:MM:SS, and DST flag.
convert_timeConvert a HH:MM wall-clock time between two IANA timezones. DST spring-forward gaps are detected and rejected.

Timer — countdown (4)

ToolPurpose
timer_startStart a countdown. Duration accepts 5m, 1h30m, 90s, 1d2h3m4s, or a bare-int seconds count. Returns 8-char ID.
timer_listAll timers with computed status (running/expired/cancelled) + remaining seconds.
timer_checkLook up a single timer.
timer_cancelIdempotent cancellation.

Stopwatch — count up (4)

ToolPurpose
stopwatch_startStart counting up from now. Returns 8-char ID.
stopwatch_stopStop a running stopwatch and return final elapsed. Idempotent — double-stop returns OK with the original stopped_at.
stopwatch_checkRead elapsed without stopping.
stopwatch_listAll stopwatches (running and stopped).

Alarm — fire at absolute time (4)

ToolPurpose
alarm_setSet an alarm. Accepts natural language ("in 4h", "tomorrow at 9am", "next Tuesday at 3pm") or absolute ISO ("2030-12-31 23:59:00"). Past times are rejected. Naive absolute strings and today/tomorrow patterns default to UTC; pass optional timezone (IANA name, e.g. "America/New_York") to anchor them in a different zone.
alarm_listAll alarms with computed status (pending/fired/cancelled) + seconds-until-fire.
alarm_checkLook up a single alarm.
alarm_cancelIdempotent cancellation.

Design notes

  • No daemons. Status is computed at read time from stored timestamps. To react when a timer expires or an alarm fires, pair with Claude Code's /loop to poll, e.g.:
    /loop 30s timer_check abc12345; if status is "expired", do X
    
  • Optional notification hook. A separate CLI entry at dist/notify-hook.js ships in the build. When wired as a UserPromptSubmit hook in ~/.claude/settings.json, it injects emoji-prefixed notifications for timers/alarms that have fired since the last check (one-shot via notified_at). See Notification hook below.
  • Persistent state at ~/.time-mcp/state.json (override via TIME_MCP_STATE_DIR env var). Atomic writes via temp-file rename, with retry-on-Windows-sharing-violation. UTF-8 throughout — emoji and accented labels round-trip cleanly. Concurrent mutations serialized via an in-process mutex. Corrupted state files are backed up to state.json.corrupted.<timestamp> instead of silently discarded.
  • Strict 1:1 JSON parity with the prior Python implementation for valid sequential calls. One observable behavior change in 0.2.0: stopwatch_stop is now idempotent (matches timer_cancel and alarm_cancel).
  • All datetimes stored as UTC ISO 8601. Timezone-aware everywhere inside the server; conversion happens only at the rendering boundary.
  • DST-correct: convert_time rejects nonexistent wall-clock times (DST spring-forward gap) via a UTC round-trip check.

Prerequisites

  • Node.js 24 or newer

Installation

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

The build emits dist/index.js (MCP server) and dist/notify-hook.js (hook CLI).

Register with Claude Code

Add to your MCP config (e.g., ~/.claude/local-marketplace/mcp-host/.mcp.json):

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

Then run /reload-plugins in Claude Code. Tools appear under the mcp__time-mcp__* prefix.

Notification hook (optional)

Wire dist/notify-hook.js into Claude Code so timer expirations and alarm fires appear as in-session context on your next prompt — no /loop polling required for the basic "tell me when it fires" use case.

Add to ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node C:/path/to/time-mcp/dist/notify-hook.js",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

On every prompt you submit (including /loop iterations), the hook reads ~/.time-mcp/state.json, finds timers with status expired and alarms with status fired that haven't yet been notified, emits one notification per item to Claude as additionalContext, and marks them notified so they don't repeat. Output looks like:

🔔 Timer 'deploy check' (wxZ0Sg3B) expired 4m ago
🔔 Alarm 'meeting prep' (a8Kp2Lw9) fired 12s ago

The hook fails silently — any unexpected error returns exit code 0 with no output, so a malformed state file or missing build never blocks your prompt.

Development

npm run typecheck   # tsc --noEmit
npm run lint        # eslint src tests --max-warnings 0
npm test            # vitest run — 92 tests across 9 files
npm run build       # emit dist/

The test suite uses process.env.TIME_MCP_STATE_DIR (set to a per-test tmp dir) to isolate state, so it never touches your real ~/.time-mcp/state.json. A mutex regression test races 50 concurrent withState callers and asserts no lost updates; a corrupted-state test verifies the .corrupted.<timestamp> backup behavior; a DST spring-forward test pins fake timers to 2026-03-08 and verifies the round-trip gap detection.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados