Skip to main content
Glama
temporal-mcp-server

temporal-mcp-server

temporal-mcp-server

npm version

時間、タイムゾーン、期間のツール向けのMCPサーバー。

stdio経由のローカル実行(Claude Desktop、Claude Code、あらゆるローカルMCPクライアント)、HTTP経由のローカル実行、またはホステッドインスタンスの利用—同じツール、同じコード、3つの実行方法です。

公開インスタンスはCloudflare Workers上で https://time.somamcp.com/mcp として動作しています:

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

somamcp を基盤としており、MCPの配管、テレメトリー、両ランタイム向けのヘルス/イントロスペクションエンドポイントを提供します。時間ロジックは純粋で関数型であり、functype を使用しています。

ツール

ツール

目的

get_current_time

現在時刻をエポック、UTC ISO-8601、任意のIANAタイムゾーンの現地時刻として返します

convert_timezone

ISO-8601タイムスタンプをターゲットタイムゾーンで表示します

add_duration

ISO-8601期間を加算・減算します。カレンダーを考慮した月の算術演算を行います

time_between

2つのタイムスタンプ間の経過時間を、整数単位と読みやすい要約で返します

somamcp はまた、info ツールと /health、/health/detail、/info、/dashboard エンドポイントを登録します。

知っておくべき挙動

月の算術演算はオーバーフローせずクランプされます。 2026-01-31 に対して P1M で add_duration を実行すると、2026-03-03 ではなく 2026-02-28 を返します。長い月の月末に「1ヶ月」を加えると、短い月の月末になります。

オフセットはゾーンごとではなく各瞬間ごとに解決されます。 America/New_York は8月には -04:00、1月には -05:00 を報告します。DSTはランタイムのtzデータベースから取得されるため、ここに古くなり得るオフセットテーブルはありません。

エラーにはヒントが含まれます。 不明なタイムゾーンは、不正な値 と 期待される形式を返すため、呼び出し側エージェントは再度推測する代わりに自分自身を修正できます。

Related MCP server: mcp-datetimeday

ローカルMCPサーバーとして実行

stdioがデフォルトであり、ローカルクライアントが期待するモードです。何もホストされず、ポートで待ち受けることもありません。クライアントがプロセスを起動し、stdin/stdoutを介して通信します。

Claude Code

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

Claude Desktop

claude_desktop_config.json に追加:

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

macOSではこのファイルは ~/Library/Application Support/Claude/claude_desktop_config.json にあり、Windowsでは %APPDATA%\Claude\claude_desktop_config.json にあります。編集後、Claude Desktopを再起動してください。

クローンからの実行

npmを経由したくない場合は:

pnpm install
pnpm build
pnpm start          # stdio

次に、ビルドされたエントリーポイントをクライアントに指定します:

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

パッケージは temporal-mcp-server バイナリもインストールするため、グローバルインストール(npm i -g temporal-mcp-server)すると、その名前をそのままコマンドとして使用できます。

動作確認

サーバーはstdout上でJSON-RPCを話すため、手動で操作できます:

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

stdoutに出力されるのはJSON-RPCのみで、ログはstderrに出力されるため、パイプは安全です。

HTTP経由でローカル実行

stdioではなくストリーム可能なHTTPを話すクライアント向け:

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

これは同じサーバーと同じツールです。トランスポートだけが異なります。

Cloudflare Workers上でリモート実行

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

cf:deploy はまず pnpm build を実行します。これには check:worker が含まれており、Node組み込みを含むバンドルはCloudflareに到達する前に失敗します。

継続的デプロイ

デプロイはGitHub Actionsではなく Cloudflare Workers Builds を介して実行されるため、Cloudflare APIトークンはGitHubに一切保存されません。Cloudflareは独自のGitHub Appを通じてリポジトリに接続します。

ダッシュボードで一度設定します(Workers & Pages → temporal-mcp-server → Settings → Build):

フィールド

値

デプロイコマンド

pnpm cf:deploy

ビルドコマンド

(空のまま — cf:deploy がビルド)

ルートディレクトリ

(リポジトリルート)

デプロイコマンドをパッケージスクリプトに指定することで、ゲーティングロジックをバージョン管理下に置けます。ダッシュボードには安定した1行だけを保持します。ダッシュボードのWorker名は、wrangler.jsonc の name(temporal-mcp-server)と一致している必要があります。一致しないとビルドが失敗します。

ビルドイメージにはpnpmが同梱され、.nvmrc が尊重されます(当リポジトリはNode 24を指定)。本番以外のブランチはデフォルトで npx wrangler versions upload を使用するため、ブランチへのプッシュは本番デプロイに触れずにプレビューバージョンを生成します。

MCPエンドポイントは /mcp にあります。ベアラートークンを要求するには:

wrangler secret put MCP_AUTH_TOKEN

MCP_AUTH_TOKEN が設定されている場合、/mcp への未認証の呼び出しは401を受け取ります。未設定のままにするとエンドポイントは公開されます。時計としては妥当ですが、他の用途にはあまり向きません。

オプションの vars: GIT_COMMIT と ENVIRONMENT は、info ツールと /info によって公開されます。

デプロイされたWorkerにクライアントを接続する

公開インスタンスはカスタムドメインから提供されます:

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

トークンを設定している場合は、ヘッダーとして渡します:

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

ヘルスチェック: https://time.somamcp.com/health.

pnpm cf:dev は同じものを http://localhost:8787/mcp で提供するため、デプロイ前にローカルのworkerdインスタンスにクライアントを向けることができます。

workerが somamcp/edge をインポートする理由

somamcp のルートバレルは node:fs をインポートするヘルパーを再エクスポートします。Workerからインポートすると、Node組み込みがバンドルに取り込まれます。そのため src/worker.ts は somamcp/edge をインポートし、pnpm check:worker は node: インポート、ベアのNode組み込み、またはルートの somamcp 指定子がworkerバンドルに到達した場合にビルドを失敗させます。

このチェックは、ファイル名の一致ではなく dist/worker.js から実際のインポートグラフを辿ります。バンドラーはNodeエントリと共有するコードを生成された名前のチャンクに巻き上げるため、ファイル名グロブはリークを運ぶ可能性が最も高いファイルを正確にスキップしてしまいます。

nodejs_compat は意図的に wrangler.jsonc で有効化されていません。Node組み込みが万一届いた場合、静かにシムされるのではなく、ビルドは明示的に失敗すべきです。

wrangler.jsonc の alias ブロック

xsschema(fastmcpを介して推移的に)は、動的インポートを通じてサポートするすべてのスキーマライブラリ(valibot、effect、sury)をプローブします。我々はzodのみを使用するため、これらのブランチは実行されませんが、esbuildは依然として指定子を解決する必要があります。これらは未使用の3つのライブラリをインストールする代わりに、空のモジュールにエイリアスされます。

アーキテクチャ

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) はサーバーを構築するのではなく受け取るため、両方のエントリポイントが同一のツールを登録します。clock.ts、tools.ts、index.ts のいずれも process、ファイルシステム、Node組み込みに一切触れません。

失敗は値です。clock.ts のすべての失敗し得る関数は Either<TemporalError, T> を返します。ツール層は Left をMCPエラー結果に折り畳みます。スタック巻き戻しに依存するものは一切ないため、同じロジックが両ランタイムで変更なく実行できます。

開発

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 は、実際の Request オブジェクトをMCPワイヤプロトコル経由でWorkerの fetch ハンドラに送り込むため、統合の破損はデプロイ後ではなくCIで表面化します。

ライセンス

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
    ResponsivenessOutdated data

    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
      112 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
      11 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.
      6
      243 npm
      2
      MIT