Skip to main content
Glama
temporal-mcp-server

temporal-mcp-server

temporal-mcp-server

npm version

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/mcp

Construido 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

get_current_time

Hora actual como epoch, ISO-8601 UTC y hora de pared en cualquier zona IANA

convert_timezone

Representa una marca de tiempo ISO-8601 en una zona horaria destino

add_duration

Suma o resta una duración ISO-8601, con aritmética de meses consciente del calendario

time_between

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-server

Claude 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          # stdio

Luego 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.js

Solo 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 PORT

Es 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 + deploy

cf: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

pnpm cf:deploy

Comando de compilación

(dejar vacío — cf:deploy compila)

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_TOKEN

Con 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/mcp

Con 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-safe

test/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 tools
add_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.

infoA
Read-only
Inspect

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

    A3.8/5.0

    Scored across 5 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      The 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 back
      167 npm
      25
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A 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.
      5
      1
      MIT
    • A
      license
      D
      quality
      C
      maintenance
      A 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.
      3
      10 npm
      7
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP 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.
      2
      6
      443 npm
      3
      MIT