TimeMCP

TimeMCP

時刻とタイムゾーンのツールを提供する Model Context Protocol（MCP）サーバーです。 stdio（デフォルト）またはストリーミング可能な HTTP を介して動作し、 mark3labs/mcp-go で構築されています。

ツール

get_current_time

指定したタイムゾーンまたはシステムのタイムゾーンで現在時刻を返します。

引数	型	必須	説明
timezone	string	いいえ	IANA タイムゾーン。デフォルトは TIME_DEFAULT_TIMEZONE、次にシステムのタイムゾーンです

レスポンス例：

Current time in Europe/Warsaw (CEST, UTC+02:00): Monday, 2025-04-09 15:30:45

convert_time

あるタイムゾーンの時刻を別のタイムゾーンに変換します。

引数	型	必須	説明
source_timezone	string	いいえ	変換元の IANA タイムゾーン。デフォルトは設定済みのデフォルトです
time	string	いいえ	HH:MM 形式の時刻。デフォルトは現在時刻です
target_timezone	string	はい	変換先の IANA タイムゾーン

レスポンス例：

Time conversion: 2025-04-09 15:30 in Europe/Warsaw → 2025-04-09 09:30 in America/New_York

describe_time

柔軟な日付／時刻文字列を解析し、現在との関係を説明します。 機械で利用できる RFC 3339 タイムスタンプと、人が読みやすい説明文を返すため、 呼び出し側で日付の計算を行う必要はありません。

対応する入力には、絶対日付（July 4th, 1776、22:08、 Thursday, July 20 2026）や相対表現（now、today、tomorrow、 yesterday、next/last/this <weekday>、単独の<weekday>、 in N minutes/hours/days/weeks/months/years、N ... ago、 next/last week/month/year）があり、末尾に at <time> を付けることもできます。

曖昧な入力の場合は推測せず、ラベル付きの候補を返します。 対象の日付と一致しない曜日、mm/dd と dd/mm の違い、 30 日以上前の日付で年が指定されていない場合が該当します。

引数	型	必須	説明
date	string	はい	解釈する日付／時刻の表現
timezone	string	いいえ	「現在」の基準となるタイムゾーン。デフォルトは前述のとおりです

レスポンス例：

input:       "tomorrow at 5pm"
machine:     2026-10-24T17:00:00-04:00
human:       tomorrow at 5:00 PM
tense:       future
perspective: tomorrow evening

ビルドと実行

Taskfile.yml で一般的なコマンドを実行できます。go を直接使うこともできます。

task build                       # go build -o bin/mcp-time .
task run                         # stdio transport
task run:http                    # HTTP transport on :8080
task run:http:auth               # HTTP transport with JWT auth
task test                        # unit tests
task test-client                 # stdio smoke test via examples/test_client.go
task check                       # fmt:check, vet, lint, test

--hash-password を使うと、パスワードを読み込んで PBKDF2 ハッシュを出力します。または、 --generate-token を使うと、静的なベアラートークンを生成します。 これらの認証情報フラグはサーバー設定の読み込み前に終了し、同時には使用できません。

クライアント設定

Claude Desktop（stdio トランスポート）：

{
  "mcpServers": {
    "time": {
      "command": "/Path/To/Your/Bin/mcp-time"
    }
  }
}

MCP 互換クライアントであれば、ツールを検出して呼び出し、整形されたレスポンスを読み取れます。

HTTP トランスポート

--transport=http（必要に応じて --auth-enabled）を指定してサーバーを起動します。 MCP エンドポイントは POST {TIME_HTTP_PATH}（デフォルトは /mcp）です。 ヘルスチェックのエンドポイントは GET /health です。独立した capabilities エンドポイントはありません （ツールの検出は MCP の tools/list を介して行います）。

CORS

CORS はデフォルトで無効です。 有効にした場合も、明示的に許可リストに追加されていないオリジンは許可されません。

TIME_HTTP_CORS_ORIGINS には、カンマ区切りの許可リストを指定します。

• ホスト名：example.com
• ホストとポート：localhost:3000、127.0.0.1:8080
• 完全な URL：https://app.example.com（ホストに正規化されます）
• ワイルドカードサブドメイン：*.example.com（example.com とすべてのサブドメインに一致します）
• *（認証が無効な場合のみ）

TIME_AUTH_ENABLED=true の場合、* の指定があると起動時に拒否されます。 プリフライトとレスポンスのヘッダーは、許可されたオリジンに対してのみ出力されます。

JWT 認証

トークンを生成します（シークレットは 32 文字以上である必要があります）。

export TIME_AUTH_SECRET_KEY="your-256-bit-secret-key-here"
go run . --generate-token \
  --token-user-id="user123" --token-username="john" --token-role="admin"

各 HTTP リクエストにトークンを含めます。

curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/mcp

OAuth 2.1（claude.ai カスタムコネクター）

TIME_OAUTH_ENABLED=true を設定すると、claude.ai、Claude Desktop、モバイルのカスタムコネクター、または Claude Code の /mcp ログインで OAuth を有効にできます。 OAuth はオプトイン方式です。既存の stdio および静的 JWT の設定は引き続き動作します。

以下の環境変数を設定します。

• TIME_OAUTH_ENABLED：デフォルトは false です。
• TIME_OAUTH_ISSUER：nginx のプレフィックスを含む公開ベース URL が必須です。 例：https://karma.example/time。
• TIME_OAUTH_RESOURCE：公開 MCP URL が必須です。例： https://karma.example/time/mcp。 これは公開 URL です。TIME_HTTP_PATH はローカルのエンドポイントパスです。
• TIME_OAUTH_LOGIN_USER：オペレーターから提供されるログインユーザー名が必須です。
• TIME_OAUTH_LOGIN_PASSWORD_HASH：mcp-time -hash-password で生成した PBKDF2 ハッシュが必須です。
• TIME_OAUTH_ACCESS_TTL：デフォルトは 1h です。
• TIME_OAUTH_REFRESH_TTL：デフォルトは 720h です。アクセストークンの TTL より長くする必要があります。

コマンド引数にパスワードを含めずに、パスワードハッシュを生成します。

bin/mcp-time -hash-password

OAuth を有効にすると、TIME_AUTH_ENABLED=false であっても認証が強制的に有効になります。 TIME_AUTH_SECRET_KEY は 32 バイト以上である必要があります。OAuth アクセストークンの署名に使用されます。 OAuth の設定が無効な場合、起動に失敗します。 OAuth のブール値や TTL の値が空の場合は、デフォルト値が使用されます。 CORS が有効な場合、TIME_HTTP_CORS_ORIGINS の * は拒否されます。

OAuth はサーバーのルートに以下のルートをマウントします。

• /.well-known/oauth-protected-resource[/<resource path>]
• /.well-known/oauth-authorization-server[/<issuer path>]
• /authorize、/login、/token、/register

Well-known ルートは、パスのサフィックスがないディスカバリードキュメントと、あるドキュメントの両方を提供します。 /register は動的クライアント登録に対応しており、認可では PKCE S256 を使用します。 OAuth が有効なときにトークンがない、または無効な場合は、WWW-Authenticate: Bearer ... resource_metadata="..." とともに HTTP 401 が返されます。 このチャレンジによって、claude.ai は OAuth フローを開始します。 有効な OAuth トークンでもスコープが間違っている場合は、HTTP 403 insufficient_scope が返されます。 OAuth が無効な場合、未認証のツール呼び出しはこれまでと同様に MCP ツールエラーを返します。 /health は引き続き認証不要です。

公開 MCP URL を使ってカスタムコネクターを作成します。

https://karma.example/time/mcp

デプロイ済みのインスタンスでは https://karma.rrj.pl/time/mcp を使用します。 Client ID と Client Secret は空欄のままにします。 オペレーターから提供されたユーザー名とパスワードでログインします。

Claude Code の場合は、ヘッダーなしでプロジェクトの .mcp.json に以下を追加し、/mcp を実行して OAuth ログインを完了します。

{
  "mcpServers": {
    "time": {
      "type": "http",
      "url": "https://karma.example/time/mcp"
    }
  }
}

または、--generate-token を使って静的ベアラートークンを生成し（JWT 認証を参照）、ヘッダーとして設定します。

{
  "mcpServers": {
    "time": {
      "type": "http",
      "url": "https://karma.example/time/mcp",
      "headers": {
        "Authorization": "Bearer <operator-issued-token>"
      }
    }
  }
}

サーバーは OAuth の状態（登録済みクライアント、コード、リフレッシュトークン）をメモリに保存するため、サーバーを再起動するとコネクターから再ログインする必要があります。 静的な TIME_AUTH ベアラートークンは、署名シークレット、issuer、audience が同じであれば、再起動後も引き続き使用できます。

nginx が /time を削除する場合は、/time/authorize、/time/login、/time/token、/time/register も、それぞれ対応するサーバールートにプロキシしてください。 また、ホストルートの /.well-known/* リクエストも転送し、/.well-known/oauth-protected-resource/time/mcp のような派生パスを保持してください。 サーバールートの認可ルートは、issuer のプレフィックス付きで公開されます。

設定

変数	デフォルト	説明
TIME_DEFAULT_TIMEZONE	system timezone	すべてのツールで使用するデフォルトの IANA タイムゾーン
TIME_HTTP_ADDRESS	:8080	HTTP リッスンアドレス
TIME_HTTP_PATH	/mcp	MCP エンドポイントのパス
TIME_HTTP_STATELESS	false	セッションなしでストリーミング可能な HTTP トランスポートを実行します
TIME_HTTP_HEARTBEAT	30s	SSE ハートビート間隔
TIME_HTTP_TIMEOUT	30s	読み取り、書き込み、シャットダウンのタイムアウト
TIME_HTTP_SESSION_IDLE_TTL	5m	アイドル状態のセッションを破棄するまでの時間
TIME_HTTP_DISABLE_LOCALHOST_PROTECTION	true	DNS リバインディングのチェックを無効にします（TimeMCP はリバースプロキシの背後で実行されます）
TIME_HTTP_CORS_ENABLED	false	CORS ラッパーを有効にします
TIME_HTTP_CORS_ORIGINS	empty	カンマ区切りのオリジン許可リスト
TIME_AUTH_ENABLED	false	HTTP ツール呼び出しで JWT を必須にします
TIME_AUTH_SECRET_KEY	empty	HMAC シークレット。認証を有効にする場合は必須です
TIME_AUTH_ISSUER	TimeMCP	想定される JWT 発行者
TIME_AUTH_AUDIENCE	TimeMCP-user	想定される JWT オーディエンス
TIME_OAUTH_ENABLED	false	OAuth コネクターのログインを有効にします
TIME_OAUTH_ISSUER	empty	nginx のプレフィックスを含む公開ベース URL
TIME_OAUTH_RESOURCE	empty	公開 MCP URL
TIME_OAUTH_LOGIN_USER	empty	オペレーターが指定するログインユーザー名
TIME_OAUTH_LOGIN_PASSWORD_HASH	empty	--hash-password で生成したハッシュ
TIME_OAUTH_ACCESS_TTL	1h	アクセストークンの有効期間
TIME_OAUTH_REFRESH_TTL	720h	リフレッシュトークンの有効期間。アクセストークンの TTL より長くする必要があります

開発

• 単体テストはコードと同じ場所にあります（*_test.go）。task test または go test -race ./... で実行してください。
• examples/test_client.go は、従来の 2025-11-25 初期化ハンドシェイクを確認し、 stdio でのみ MCP 2026-07-28（server/discover、tools/list、tools/call）を _meta とともに実行します。 すべてのツールを呼び出し、プロトコルまたはツールのエラーが発生すると失敗します。
• docs/ARCHITECTURE.md では各要素の連携について説明し、docs/STATUS.md には 現在のツールチェーンと健全性を記録しています。また、docs/OPEN_ITEMS.md には既知の課題を列挙しています。
• 廃止されたドキュメントや古いレポートは docs/retired/ に置きます（追跡対象）。 新しいレポートは docs/reports/ に置きます（gitignore 対象）。

依存関係

• github.com/mark3labs/mcp-go v1：MCP プロトコルとトランスポート
• github.com/golang-jwt/jwt/v5：JWT 認証
• github.com/araddon/dateparse：柔軟な絶対日付解析
• golang.org/x/term：--hash-password 用の入力文字を表示しないパスワード入力

サポート対象のタイムゾーン

Europe/Warsaw、America/New_York、Asia/Tokyo、Australia/Sydney、Africa/Cairo など、IANA タイムゾーン識別子を使用できます。