temporal-mcp-server

temporal-mcp-server

時間、タイムゾーン、期間のツールを提供する 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

両方の実行環境に MCP の接続機能、テレメトリ、ヘルスチェック／イントロスペクションのエンドポイントを提供する somamcp（README · npm）を基盤としています。時間の処理ロジックは純粋関数型で、functype を使用しています。

ツール

ツール	目的
get_current_time	任意の IANA タイムゾーンにおける現在時刻を、エポック、UTC ISO-8601、現地時刻で取得します
convert_timezone	ISO-8601 タイムスタンプを対象のタイムゾーンで表示します
add_duration	ISO-8601 期間を加算または減算します。月の計算ではカレンダーを考慮します
time_between	2 つのタイムスタンプ間の経過時間を、単位ごとの整数値と読みやすい要約で取得します

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

知っておくと便利な動作

日付の単位はカレンダーに基づき、時間の単位は正確です。 これにより DST が適切に処理されます。また、ISO-8601 と Temporal に準拠しています：

米国の「秋の戻り」の期間	結果
2026-11-01T00:00-04:00 + P1D	2026-11-02T00:00 — 翌日の同じ現地時刻（実時間で25時間）
2026-11-01T00:00-04:00 + PT24H	2026-11-01T23:00 — 正確に24時間

どちらも正しく、結果は異なります。「明日」はカレンダー上の考え方ですが、「今から24時間後」は物理的な時間です。

timezone は表示だけでなく、計算も決定します。 カレンダー単位はそのタイムゾーンの現地時刻に対して適用されるため、America/New_York での add_duration はニューヨークの人が期待する動作になります。

月の計算では、繰り越さずに末日に合わせます。 2026-01-31 に P1M を加えると、2026-03-03 ではなく 2026-02-28 が返されます。

オフセットはタイムゾーンごとではなく、時点ごとに解決されます。 America/New_York は8月には -04:00、1月には -05:00 を返します。DST は実行環境のタイムゾーンデータベースから取得するため、古くなるオフセット表はありません。

タイムゾーンのないタイムスタンプは、指定されたタイムゾーンで解釈されます。 America/New_York を指定した 2026-11-01T00:00:00 は、ニューヨークの午前0時を意味します。ホストのタイムゾーンにフォールバックすることはありません。そうすると、ノートパソコンと Worker で異なる結果になるためです。

タイムスタンプの解析は厳密です。 ISO-8601 形式のみ受け付けます。17 Aug 2026 はヒントとともに拒否されます。new Date() であればこの値を受け入れ、プロセスが実行されたタイムゾーンに基づいて解釈していたでしょう。

経過時間の各要素は符号が統一されます。 time_between は過去にさかのぼる区間の場合、days／hours／minutes／seconds のすべてを負の値で返すため、合計しても正しい値になります。また、direction は past／future／same のいずれかを返します。

エラーにはヒントが含まれます。 不明なタイムゾーンの場合、無効な値と期待される形式の両方が返されるため、呼び出し元のエージェントは推測を繰り返さずに値を修正できます。

ローカル 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）を行うと、その名前をコマンドとして直接使用できます。

このリポジトリでの作業

チェックイン済みの .mcp.json はローカルビルドを temporal サーバーとして登録するため、Claude Code はホストされたインスタンスではなく、あなたの変更を取り込みます：

{
  "mcpServers": {
    "temporal": {
      "command": "node",
      "args": ["dist/node.js"]
    }
  }
}

まず pnpm build を実行してください。設定は dist/ を参照するため、ビルドしていないチェックアウトには起動できるものがありません。

動作の確認

サーバーは 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 を返します。未設定の場合、エンドポイントは公開されます。時計なら妥当ですが、それ以外ではあまりおすすめできません。

ビルドの来歴

scripts/deploy.mjs はデプロイに GIT_COMMIT、GIT_BRANCH、BUILD_DATE を記録するため、info ツールと /info で、実行中のバージョンを正確に確認できます：

curl -s https://time.somamcp.com/info   # protected; also available via the `info` MCP tool

Workers Builds はビルド中に WORKERS_CI_COMMIT_SHA と WORKERS_CI_BRANCH を公開しますが、ビルド変数は実行時には読み取れません。Worker の変数として引き渡す必要があり、デプロイスクリプトがそれを行います。ローカルで pnpm cf:deploy を実行すると git rev-parse にフォールバックします。また、変更のあるツリーからのデプロイには <sha>-dirty が記録され、実際にはそうでないコミットであるかのように示すことはありません。

デプロイ済み 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 バンドルに含まれている場合、ビルドを失敗させます。

詳しくは、somamcp のエッジランタイムに関するドキュメントをご覧ください。エッジで動作する機能と動作しない機能をまとめた機能互換性表も掲載されています。stdio、セッション、reportProgress、複数結果のリソースはいずれも Node 専用です。

このチェックでは、ファイル名との照合ではなく、dist/worker.js から実際のインポートグラフをたどります。バンドラーは Node 用エントリーポイントと共有されるコードを、生成された名前のチャンクにまとめます。ファイル名の glob では、リークが最も起きやすいファイルをまさに見逃してしまいます。

wrangler.jsonc では、意図的に nodejs_compat を有効にしていません。Node の組み込みモジュールが入り込んだ場合、黙って shim で置き換えるのではなく、ビルドを明示的に失敗させるべきです。

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 は、MCP ワイヤープロトコル経由で実際の Request オブジェクトを Worker の fetch ハンドラーに渡します。そのため、統合部分の不具合はデプロイ後ではなく CI で明らかになります。

ライセンス

MIT