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

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

ツール

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

デプロイコマンドをパッケージスクリプトに指定することで、ゲーティングロジックをバージョン管理下に置けます。ダッシュボードには安定した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