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

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

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