temporal-mcp-server
temporal-mcp-server
Servidor MCP para herramientas de hora, zona horaria y duración.
Ejecútalo localmente a través de stdio (Claude Desktop, Claude Code, cualquier cliente MCP local), localmente a través de HTTP, o usa la instancia alojada — las mismas herramientas, el mismo código, tres formas de ejecutarlo.
Una instancia pública se ejecuta en Cloudflare Workers en https://time.somamcp.com/mcp:
claude mcp add --transport http temporal https://time.somamcp.com/mcpConstruido sobre somamcp, que proporciona la infraestructura MCP, la telemetría y los endpoints de salud/introspección para ambos runtimes. La lógica temporal es pura y funcional, usando functype.
Herramientas
Herramienta | Propósito |
| Hora actual como epoch, ISO-8601 UTC y hora de pared en cualquier zona IANA |
| Representa una marca de tiempo ISO-8601 en una zona horaria destino |
| Suma o resta una duración ISO-8601, con aritmética de meses consciente del calendario |
| Tiempo transcurrido entre dos marcas de tiempo, en unidades completas más un resumen legible |
somamcp también registra una herramienta info y los endpoints /health, /health/detail, /info y /dashboard.
Comportamiento que conviene saber
La aritmética de meses satura en lugar de desbordar. add_duration sobre 2026-01-31 con P1M devuelve 2026-02-28, no 2026-03-03. Añadir «un mes» al final de un mes largo aterriza en el final del mes corto.
Los offsets se resuelven por instante, no por zona. America/New_York informa -04:00 en agosto y -05:00 en enero. El horario de verano (DST) proviene de la base de datos tz del runtime, por lo que aquí no hay una tabla de offsets que pueda quedar obsoleta.
Los errores llevan una pista. Una zona horaria desconocida devuelve el valor incorrecto y el formato esperado, para que un agente que llama pueda corregirse en lugar de volver a adivinar.
Related MCP server: mcp-datetimeday
Ejecutar como servidor MCP local
Stdio es el modo predeterminado y el que esperan los clientes locales. Nada está alojado, nada escucha en un puerto — tu cliente lanza el proceso y se comunica con él a través de stdin/stdout.
Claude Code
claude mcp add temporal -- npx -y temporal-mcp-serverClaude Desktop
Añádelo a claude_desktop_config.json:
{
"mcpServers": {
"temporal": {
"command": "npx",
"args": ["-y", "temporal-mcp-server"]
}
}
}En macOS, ese archivo se encuentra en ~/Library/Application Support/Claude/claude_desktop_config.json; en Windows, en %APPDATA%\Claude\claude_desktop_config.json. Reinicia Claude Desktop después de editarlo.
Ejecutar desde un clon
Si prefieres no pasar por npm:
pnpm install
pnpm build
pnpm start # stdioLuego apunta tu cliente al punto de entrada compilado:
claude mcp add temporal -- node /absolute/path/to/temporal-mcp-server/dist/node.js{
"mcpServers": {
"temporal": {
"command": "node",
"args": ["/absolute/path/to/temporal-mcp-server/dist/node.js"]
}
}
}El paquete también instala un binario temporal-mcp-server, por lo que una instalación global (npm i -g temporal-mcp-server) te permite usar ese nombre directamente como comando.
Verificar que funciona
El servidor habla JSON-RPC en stdout, así que puedes manejarlo manualmente:
printf '%s\n%s\n%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"1.0.0"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_current_time","arguments":{"timezone":"Asia/Tokyo"}}}' \
| node dist/node.jsSolo el JSON-RPC va a stdout; los registros van a stderr, por lo que el pipe es seguro.
Ejecutar localmente a través de HTTP
Para clientes que usan HTTP en streaming en lugar de stdio:
pnpm start:http # http://localhost:3333/mcp — override the port with PORTEs el mismo servidor y las mismas herramientas; solo difiere el transporte.
Ejecutar de forma remota en Cloudflare Workers
pnpm cf:dev # local workerd runtime
pnpm cf:deploy # build + edge-safety check + deploycf:deploy ejecuta pnpm build primero, que incluye check:worker — por lo que un bundle que contenga un built-in de Node falla antes de que nada llegue a Cloudflare.
Despliegue continuo
Los despliegues se ejecutan a través de Cloudflare Workers Builds en lugar de GitHub Actions, por lo que no se almacena ningún token de API de Cloudflare en GitHub — Cloudflare se conecta al repositorio mediante su propia GitHub App.
Configúralo una vez en el panel (Workers & Pages → temporal-mcp-server → Settings → Build):
Campo | Valor |
Comando de despliegue |
|
Comando de compilación | (dejar vacío — |
Directorio raíz | (raíz del repositorio) |
Apuntar el comando de despliegue a un script del paquete mantiene la lógica de control en el control de versiones; el panel contiene una única línea estable. El nombre del Worker en el panel debe coincidir con name en wrangler.jsonc (temporal-mcp-server), o la compilación fallará.
La imagen de compilación incluye pnpm y respeta .nvmrc (la nuestra fija Node 24). Las ramas que no son de producción usan por defecto npx wrangler versions upload, por lo que los pushes de ramas producen versiones de vista previa sin tocar el despliegue en vivo.
El endpoint MCP está en /mcp. Para exigir un token de portador:
wrangler secret put MCP_AUTH_TOKENCon MCP_AUTH_TOKEN configurado, las llamadas no autenticadas a /mcp reciben un 401. Déjalo sin configurar y el endpoint será público — razonable para un reloj, no para mucho más.
vars opcionales: GIT_COMMIT y ENVIRONMENT se muestran mediante la herramienta info y /info.
Conectar un cliente al worker desplegado
La instancia pública se sirve desde un dominio personalizado:
claude mcp add --transport http temporal https://time.somamcp.com/mcpCon un token configurado, pásalo como encabezado:
claude mcp add --transport http temporal https://time.somamcp.com/mcp \
--header "Authorization: Bearer $MCP_AUTH_TOKEN"Comprobación de salud: https://time.somamcp.com/health.
pnpm cf:dev sirve lo mismo en http://localhost:8787/mcp, así que puedes apuntar un cliente a una instancia local de workerd antes de desplegar.
Por qué el worker importa somamcp/edge
El barrel raíz de somamcp reexporta helpers que importan node:fs. Importarlo desde un Worker arrastra los built-ins de Node al bundle. Por eso src/worker.ts importa somamcp/edge, y pnpm check:worker hace fallar la compilación si una importación node:, un built-in de Node sin prefijo o el especificador raíz somamcp llega al bundle del worker.
La comprobación recorre el grafo de importación real desde dist/worker.js en lugar de comparar nombres de archivo — el bundler eleva el código compartido con la entrada de Node a un chunk con un nombre generado, y un glob de nombres de archivo omitiría precisamente el archivo con más probabilidades de contener una fuga.
nodejs_compat está deliberadamente no habilitado en wrangler.jsonc. Si algún built-in de Node llegara, la compilación debería fallar ruidosamente en lugar de ser silenciosamente reemplazado.
El bloque alias en wrangler.jsonc
xsschema (transitivo, a través de fastmcp) sondea cada librería de esquemas que soporta — valibot, effect, sury — mediante importación dinámica. Solo usamos zod, así que esas ramas nunca se ejecutan, pero esbuild todavía tiene que resolver los especificadores. Se les asigna un alias a un módulo vacío en lugar de instalar tres librerías no utilizadas.
Arquitectura
src/
clock.ts pure time logic — Either<TemporalError, T>, no I/O, no globals
tools.ts MCP tool registration; takes a server, creates none
index.ts library surface (runtime-agnostic)
node.ts entry: somamcp -> stdio + httpStream
worker.ts entry: somamcp/edge -> export default { fetch }registerTemporalTools(server) recibe el servidor en lugar de construir uno, por lo que ambos puntos de entrada registran herramientas idénticas. Nada en clock.ts, tools.ts o index.ts toca process, el sistema de archivos ni ningún built-in de Node.
Los fallos son valores. Cada función que puede fallar en clock.ts devuelve Either<TemporalError, T>; la capa de herramientas convierte un Left en un resultado de error MCP. Nada depende del desenrollado de la pila, que es lo que permite que la misma lógica se ejecute sin cambios en ambos runtimes.
Desarrollo
pnpm validate # format + lint + typecheck + test + build
pnpm test # 34 tests
pnpm check:worker # verify the worker bundle is edge-safetest/worker.spec.ts pasa objetos Request reales a través del manejador fetch del Worker mediante el protocolo de cable MCP, por lo que las roturas de integración aparecen en CI en lugar de después de un despliegue.
Licencia
MIT
Available Tools
5 toolsadd_durationAInspect
Add an ISO-8601 duration to a timestamp, in a timezone. Date units (Y/M/D) are calendar-aware: P1D across a DST boundary keeps the same wall-clock time the next day, and P1M on Jan 31 clamps to the end of February. Time units (H/M/S) are exact elapsed time, so PT24H really is 24 hours. Prefix the duration with '-' to subtract.
Inputs: duration (required), isoTimestamp (required), timezone.
convert_timezoneBInspect
Render an ISO-8601 timestamp as wall-clock time in a target timezone.
Inputs: isoTimestamp (required), targetTimezone (required), sourceTimezone.
get_current_timeAInspect
Return the current time as an epoch, a UTC ISO-8601 timestamp, and the wall-clock time in a given timezone.
Inputs: timezone.
infoARead-onlyInspect
Returns identity and build information for this server (name, version, build commit, runtime, capability counts)
Inputs: no named parameters.
time_betweenAInspect
Exact elapsed time between two ISO-8601 timestamps, broken into days/hours/minutes/seconds plus a human-readable summary. All components share one sign, so they sum correctly; direction is 'past', 'future', or 'same'.
Inputs: to (required), from (required), timezone.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct operation: server metadata, current time retrieval, timezone conversion, duration arithmetic, and elapsed-time calculation. There is no overlap in inputs or intent, and descriptions make the boundaries unambiguous.
Three tools follow a clean verb_noun pattern (get_current_time, convert_timezone, add_duration), but 'info' is a bare noun and 'time_between' is a prepositional phrase rather than verb-led. The deviations are minor and still readable.
Five tools is well-scoped for a focused time-utility server, with each tool earning its place and no redundant entries. Nothing feels padded or missing at the count level.
The core time lifecycle is covered: now, convert, shift (subtraction handled via negative prefix), and diff. Minor gaps remain around parsing/formatting arbitrary timestamp strings or listing timezones, but agents can work around these.
Maintenance
Related MCP Connectors
Timezone MCP — wraps timeapi.io (free, no auth)
MCP server for time in cities around the world, time zones, DST, conversion, and meetings.
timesheet.io MCP server - manage timers, projects, tasks and reports
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceThe Time MCP Server is a Model Context Protocol (MCP) server that provides AI assistants and other MCP clients with standardized tools to perform time and date-related operations. This server acts as a bridge between AI tools and a robust time-handling back167 npm25MIT
- AlicenseAqualityDmaintenanceA lightweight MCP server providing comprehensive date, time, and day-of-week information. It supports relative time calculations, timezone conversions, and detailed calendar metadata like week numbers and quarters.51MIT
- AlicenseDqualityCmaintenanceA lightweight MCP server that provides date and time tools, including the ability to retrieve current timestamps and parse date strings with IANA timezone support. It enables AI models to interact with the host OS clock and perform temporal calculations via stdio transport.310 npm7MIT
- AlicenseAqualityDmaintenanceMCP server providing various date/time functions including current time, timezone conversion, and relative time calculations. Supports both local stdio and remote HTTP access via Cloudflare Workers.26443 npm3MIT