temporal-mcp-server

MCP-Server für Zeit-, Zeitzonen- und Dauerwerkzeuge.

Führen Sie ihn lokal über stdio aus (Claude Desktop, Claude Code, jeder lokale MCP-Client), lokal über HTTP oder nutzen Sie die gehostete Instanz – dieselben Werkzeuge, derselbe Code, drei Möglichkeiten, ihn auszuführen.

Eine öffentliche Instanz läuft auf Cloudflare Workers unter https://time.somamcp.com/mcp:

claude mcp add --transport http temporal https://time.somamcp.com/mcp

Basiert auf somamcp, das die MCP-Infrastruktur, Telemetrie sowie Health-/Introspections-Endpunkte für beide Laufzeiten bereitstellt. Die Zeitlogik ist rein und funktional und verwendet functype.

Werkzeuge

somamcp registriert außerdem ein info-Werkzeug und die Endpunkte /health, /health/detail, /info und /dashboard.

Wissenswertes Verhalten

Monatsarithmetik begrenzt statt überzulaufen. add_duration auf 2026-01-31 mit P1M gibt 2026-02-28 zurück, nicht 2026-03-03. Das Hinzufügen von "einem Monat" zum Ende eines langen Monats landet am Ende des kurzen.

Offsets werden pro Zeitpunkt aufgelöst, nicht pro Zone. America/New_York meldet im August -04:00 und im Januar -05:00. Die Sommerzeit stammt aus der tz-Datenbank der Laufzeit, daher gibt es hier keine Offsettabelle, die veralten könnte.

Fehler enthalten einen Hinweis. Eine unbekannte Zeitzone gibt den ungültigen Wert und das erwartete Format zurück, sodass ein aufrufender Agent sich selbst korrigieren kann, statt erneut zu raten.

Related MCP server: mcp-datetimeday

Als lokaler MCP-Server ausführen

Stdio ist der Standardmodus und der Modus, den lokale Clients erwarten. Es wird nichts gehostet, nichts lauscht auf einem Port – Ihr Client startet den Prozess und kommuniziert über stdin/stdout mit ihm.

Claude Code

claude mcp add temporal -- npx -y temporal-mcp-server

Claude Desktop

Fügen Sie zu claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "temporal": {
      "command": "npx",
      "args": ["-y", "temporal-mcp-server"]
    }
  }
}

Auf macOS befindet sich diese Datei unter ~/Library/Application Support/Claude/claude_desktop_config.json; unter Windows unter %APPDATA%\Claude\claude_desktop_config.json. Starten Sie Claude Desktop nach der Bearbeitung neu.

Aus einem Klon ausführen

Wenn Sie nicht über npm gehen möchten:

pnpm install
pnpm build
pnpm start          # stdio

Dann weisen Sie Ihren Client auf den erstellten Einstiegspunkt:

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"]
    }
  }
}

Das Paket installiert außerdem eine temporal-mcp-server-Binärdatei, sodass Sie bei einer globalen Installation (npm i -g temporal-mcp-server) diesen Namen direkt als Befehl verwenden können.

Funktionsprüfung

Der Server spricht JSON-RPC auf stdout, Sie können ihn also von Hand steuern:

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

Nur JSON-RPC geht an stdout; Logs gehen an stderr, daher ist Piping sicher.

Lokal über HTTP ausführen

Für Clients, die streambares HTTP statt stdio sprechen:

pnpm start:http     # http://localhost:3333/mcp — override the port with PORT

Dies ist derselbe Server und dieselben Werkzeuge; nur der Transport unterscheidet sich.

Remote auf Cloudflare Workers ausführen

pnpm cf:dev         # local workerd runtime
pnpm cf:deploy      # build + edge-safety check + deploy

cf:deploy führt zuerst pnpm build aus, was check:worker einschließt – ein Bundle mit einem Node-Builtin schlägt also fehl, bevor etwas Cloudflare erreicht.

Kontinuierliche Bereitstellung

Deployments laufen über Cloudflare Workers Builds statt über GitHub Actions, sodass überhaupt kein Cloudflare-API-Token in GitHub gespeichert wird – Cloudflare verbindet sich über seine eigene GitHub-App mit dem Repository.

Richten Sie es einmal im Dashboard ein (Workers & Pages → temporal-mcp-server → Settings → Build):

Indem der Deploy-Befehl auf ein Paketskript zeigt, bleibt die Gate-Logik in der Versionskontrolle; das Dashboard enthält eine stabile Zeile. Der Worker-Name im Dashboard muss mit name in wrangler.jsonc übereinstimmen (temporal-mcp-server), sonst schlägt der Build fehl.

Das Build-Image enthält pnpm und berücksichtigt .nvmrc (unseres pinnt Node 24). Nicht-Produktions-Branches verwenden standardmäßig npx wrangler versions upload, sodass Branch-Pushes Vorschauversionen erzeugen, ohne die Live-Bereitstellung zu berühren.

Der MCP-Endpunkt ist unter /mcp. Um ein Bearer-Token zu verlangen:

wrangler secret put MCP_AUTH_TOKEN

Wenn MCP_AUTH_TOKEN gesetzt ist, erhalten nicht authentifizierte Aufrufe an /mcp eine 401. Wenn Sie es nicht setzen, ist der Endpunkt öffentlich – für eine Uhr vernünftig, für vieles andere nicht.

Optionale vars: GIT_COMMIT und ENVIRONMENT werden vom info-Werkzeug und /info angezeigt.

Verbinden eines Clients mit dem bereitgestellten Worker

Die öffentliche Instanz wird über eine benutzerdefinierte Domain bereitgestellt:

claude mcp add --transport http temporal https://time.somamcp.com/mcp

Mit einem gesetzten Token übergeben Sie es als Header:

claude mcp add --transport http temporal https://time.somamcp.com/mcp \
  --header "Authorization: Bearer $MCP_AUTH_TOKEN"

Health-Check: https://time.somamcp.com/health.

pnpm cf:dev liefert dasselbe unter http://localhost:8787/mcp, sodass Sie vor dem Deployment einen Client auf eine lokale workerd-Instanz richten können.

Warum der Worker somamcp/edge importiert

Das Root-Barrel von somamcp exportiert Helfer, die node:fs importieren. Wenn man es aus einem Worker importiert, zieht das Node-Builtins in das Bundle. src/worker.ts importiert daher somamcp/edge, und pnpm check:worker lässt den Build fehlschlagen, wenn ein node:-Import, ein nacktes Node-Builtin oder der Root-Spezifizierer somamcp das Worker-Bundle erreicht.

Die Prüfung durchläuft den tatsächlichen Importgraphen von dist/worker.js, anstatt Dateinamen abzugleichen – der Bundler hebt Code, der mit dem Node-Einstieg geteilt wird, in einen Chunk mit generiertem Namen an, und ein Dateinamen-Glob würde genau die Datei überspringen, die am wahrscheinlichsten ein Leck enthält.

nodejs_compat ist in wrangler.jsonc bewusst nicht aktiviert. Falls jemals ein Node-Builtin auftaucht, sollte der Build laut scheitern, statt stillschweigend ersetzt zu werden.

Der alias-Block in wrangler.jsonc

xsschema (transitiv über fastmcp) testet jede Schema-Bibliothek, die es unterstützt – valibot, effect, sury – per dynamischem Import. Wir verwenden nur zod, daher werden diese Zweige nie ausgeführt, aber esbuild muss die Spezifizierer trotzdem auflösen. Sie werden auf ein leeres Modul abgebildet, statt drei ungenutzte Bibliotheken zu installieren.

Architektur

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) nimmt den Server entgegen, statt einen zu bauen, sodass beide Einstiegspunkte identische Werkzeuge registrieren. Nichts in clock.ts, tools.ts oder index.ts berührt process, das Dateisystem oder ein Node-Builtin.

Fehler sind Werte. Jede fehlbare Funktion in clock.ts gibt Either<TemporalError, T> zurück; die Werkzeugebene faltet ein Left in ein MCP-Fehlerergebnis. Nichts hängt vom Stack-Unwinding ab, wodurch dieselbe Logik auf beiden Laufzeiten unverändert läuft.

Entwicklung

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 treibt echte Request-Objekte durch den fetch-Handler des Workers über das MCP-Wire-Protokoll, sodass Integrationsfehler bereits in der CI auftauchen statt nach einem Deployment.

Lizenz

MIT