Time MCP — Servidor de Tempo, Timers e Alarmes
danielsimonjr/time-mcp
Timers, stopwatches e alarmes para Claude com suporte a timezones IANA
Ver no GitHubServidor 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-mcp1 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
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)
| Tool | Purpose |
|---|---|
get_current_time | Current time in any IANA timezone (defaults to system zone). Returns ISO datetime, HH:MM:SS, and DST flag. |
convert_time | Convert a HH:MM wall-clock time between two IANA timezones. DST spring-forward gaps are detected and rejected. |
Timer — countdown (4)
| Tool | Purpose |
|---|---|
timer_start | Start a countdown. Duration accepts 5m, 1h30m, 90s, 1d2h3m4s, or a bare-int seconds count. Returns 8-char ID. |
timer_list | All timers with computed status (running/expired/cancelled) + remaining seconds. |
timer_check | Look up a single timer. |
timer_cancel | Idempotent cancellation. |
Stopwatch — count up (4)
| Tool | Purpose |
|---|---|
stopwatch_start | Start counting up from now. Returns 8-char ID. |
stopwatch_stop | Stop a running stopwatch and return final elapsed. Idempotent — double-stop returns OK with the original stopped_at. |
stopwatch_check | Read elapsed without stopping. |
stopwatch_list | All stopwatches (running and stopped). |
Alarm — fire at absolute time (4)
| Tool | Purpose |
|---|---|
alarm_set | Set 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_list | All alarms with computed status (pending/fired/cancelled) + seconds-until-fire. |
alarm_check | Look up a single alarm. |
alarm_cancel | Idempotent 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
/loopto 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.jsships in the build. When wired as aUserPromptSubmithook in~/.claude/settings.json, it injects emoji-prefixed notifications for timers/alarms that have fired since the last check (one-shot vianotified_at). See Notification hook below. - Persistent state at
~/.time-mcp/state.json(override viaTIME_MCP_STATE_DIRenv 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 tostate.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_stopis now idempotent (matchestimer_cancelandalarm_cancel). - All datetimes stored as UTC ISO 8601. Timezone-aware everywhere inside the server; conversion happens only at the rendering boundary.
- DST-correct:
convert_timerejects 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.