findtime.io MCP Server

@findtime/mcp-server

@findtime/mcp-server は、本番環境の findtime.io Time API（https://time-api.findtime.io）を利用する、stdio MCP ラッパーです。

このパッケージは、時刻処理をローカルで再実装するのではなく、本番 API にプロキシすることを意図しています。現在時刻、DST、変換、重複、ミーティング検索、場所の解決は、常に稼働中の API と一致する必要があります。

公開されている情報：

• npm：@findtime/mcp-server
• GitHub：https://github.com/hkchao/findtime-mcp-server
• 公式 MCP レジストリ：https://registry.modelcontextprotocol.io/?q=io.github.hkchao%2Ffindtime-mcp-server
• MCP レジストリ名：io.github.hkchao/findtime-mcp-server

ツール一覧

• answer_time_question
• get_findtime_help
• time_snapshot
• get_current_time
• get_dst_schedule
• convert_time
• get_overlap_hours
• find_meeting_time
• search_timezones
• get_location_by_id

「3pm PST to London」「what is the IANA timezone for San Francisco?」「working hours overlap for SF, Berlin, and Tokyo」「what does CST mean?」のような、曖昧な自然言語のプロンプトには、answer_time_question を優先して使用してください。このツールは、findtime.io のドメインロジックを通じてプロンプトを分類し、決定論的な Time API の処理に振り分けます。また、実際に曖昧さがある場合は、構造化された曖昧さや確認事項を返します。

MCP クライアントへのインストール

npx を使用して、公開パッケージを利用してください。

npx -y @findtime/mcp-server

エージェントの作成者は、SKILL.md を MCP 設定と一緒に配置してください。 このファイルには、Claude、Codex、Cursor、Cline、Windsurf、社内カスタムボットなどの LLM エージェントが、どのような場合に findtime.io MCP を優先するか、どのツールを呼び出すか、曖昧さやフォールバックにどう対処するかについての運用ルールが記載されています。

必要なランタイム：

• Node 20+
• FINDTIME_TIME_API_KEY：https://findtime.io/developers/keys/ で取得できる有効な findtime.io 開発者キー

任意の環境変数：

• FINDTIME_TIME_API_BASE_URL
• TIME_API_BASE_URL
• TIME_API_TIMEOUT_MS
• FINDTIME_BINDING_TYPE：任意のインストール／ワークスペースのバインディングコンテキストに使用します。サポートされている値：slack_team、workspace_id、install_id。
• FINDTIME_BINDING_VALUE：選択したバインディングタイプに対応する、インストール／ワークスペース識別子を指定します。
• FINDTIME_BINDING_HEADER：カスタムのエンタープライズ環境向けに、ヘッダー名を直接上書きします。
• FINDTIME_MCP_CLIENT_ID または FINDTIME_MCP_INSTALL_ID：安定したクライアント識別子を指定します。省略した場合、サーバーはユーザーの状態ディレクトリ内にローカルで作成します。指定されている場合、MCP ラッパーはエンタープライズ利用状況の計測のため、これを X-Findtime-User-ID として time-api に転送します。
• FINDTIME_MCP_CLIENT_TYPE
• FINDTIME_MCP_TOOL_MODE=answer-only：すべての自然言語リクエストを回答 API に送る必要があるエンタープライズボット向けに、answer_time_question、get_findtime_help、get_api_diagnostics のみを公開します。
• FINDTIME_MCP_INSTRUMENTATION_ENABLED=false：匿名の利用状況テレメトリをオプトアウトします。
• FINDTIME_MCP_USAGE_TELEMETRY_URL：デフォルトのテレメトリエンドポイントを上書きします。

呼び出しごとのエンドユーザーの帰属

Slack、Discord、Teams のボットなどのマルチユーザー MCP ホストでは、長時間稼働する @findtime/mcp-server サブプロセスを 1 つ実行しながら、各 Time API 呼び出しを、その呼び出しを開始したエンドユーザーに帰属させることができます。MCP ツール呼び出しの arguments オブジェクト内に、オプションの _endUserId フィールドを追加します。サーバーは _endUserId をツールのパラメーターから除外し、上流への X-Findtime-End-User-ID HTTP ヘッダーとしてのみ転送します。

await client.callTool({
  name: "get_current_time",
  arguments: {
    city: "Tokyo",
    _endUserId: "a3f2c1d4e5b6c7d8"
  }
});

このフィールドはオプションであり、後方互換性があります。_endUserId がない場合、null の場合、または空文字列の場合は、ヘッダーが省略され、インストールレベルの FINDTIME_MCP_CLIENT_ID または FINDTIME_MCP_INSTALL_ID の動作に従って帰属が決まります。

プライバシーに関する契約：_endUserId は、MCP ホストから提供される不透明なトークンでなければなりません。通常は、プラットフォームのユーザー ID の SHA-256 ハッシュを 16～32 桁の 16 進数に切り詰めたものを使用します。生のメールアドレス、氏名、Slack／Discord／Teams の ID、その他の個人を特定できる情報（PII）は送信しないでください。このフィールドに PII を含めないようにする責任は、ホストアプリケーションにあります。

サーバーは _endUserId を防御的に検証します。文字列であり、256 文字以下で、CR、LF、その他の制御文字を含んではなりません。サーバーが生の値をログに記録することはありません。

Cursor

{
  "mcpServers": {
    "findtime": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@findtime/mcp-server"],
      "env": {
        "FINDTIME_MCP_CLIENT_TYPE": "cursor",
        "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io",
        "FINDTIME_TIME_API_KEY": "YOUR_FINDTIME_SECRET_KEY"
      }
    }
  }
}

Codex

[mcp_servers.findtime]
command = "npx"
args = ["-y", "@findtime/mcp-server"]
enabled = true

[mcp_servers.findtime.env]
FINDTIME_MCP_CLIENT_TYPE = "codex"
FINDTIME_TIME_API_BASE_URL = "https://time-api.findtime.io"
FINDTIME_TIME_API_KEY = "YOUR_FINDTIME_SECRET_KEY"
# Optional enterprise install binding:
# FINDTIME_BINDING_TYPE = "workspace_id"
# FINDTIME_BINDING_VALUE = "YOUR_WORKSPACE_ID"

Claude Desktop

{
  "preferences": {
    "...": "keep your existing preferences here"
  },
  "mcpServers": {
    "findtime": {
      "command": "npx",
      "args": ["-y", "@findtime/mcp-server"],
        "env": {
          "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io",
          "FINDTIME_TIME_API_KEY": "YOUR_FINDTIME_SECRET_KEY"
        }
      }
    }
  }

Claude CLI / Claude Code

次を含む findtime.io を追加します。

claude mcp add --transport stdio \
  --env FINDTIME_TIME_API_BASE_URL=https://time-api.findtime.io \
  --env FINDTIME_TIME_API_KEY=YOUR_FINDTIME_SECRET_KEY \
  --env FINDTIME_MCP_CLIENT_TYPE=claude-cli \
  findtime -- npx -y @findtime/mcp-server

Claude CLI で代わりに JSON 設定を使用する場合は、次を追加します。

{
  "mcpServers": {
    "findtime": {
      "command": "npx",
      "args": ["-y", "@findtime/mcp-server"],
      "env": {
        "FINDTIME_TIME_API_BASE_URL": "https://time-api.findtime.io",
        "FINDTIME_TIME_API_KEY": "YOUR_FINDTIME_SECRET_KEY",
        "FINDTIME_MCP_CLIENT_TYPE": "claude-cli"
      }
    }
  }
}

エンタープライズ環境でのインストールでは、最低限必要な認証情報は常に API キーです。インストール環境に安定したワークスペース ID またはインストール ID がある場合は、必要に応じて次を追加します。

FINDTIME_BINDING_TYPE=workspace_id
FINDTIME_BINDING_VALUE=YOUR_WORKSPACE_ID

Slack 専用のインストールでは、次を追加します。

FINDTIME_BINDING_TYPE=slack_team
FINDTIME_BINDING_VALUE=T01ABC123

インストールの確認

まず、明示的なツール呼び出しを指示するプロンプトを使います。

Use the findtime.io MCP tool get_api_diagnostics.

次に、以下を実行します。

Use the findtime.io MCP tool get_current_time for city "Tokyo" with countryCode "JP".

これが成功したら、通常の自然言語プロンプトに戻します。

Best meeting time between New York, Sydney, and Mumbai?

ローカル開発

ワークスペースのバージョンを直接実行します。

npm run mcp:start

サーバーは、以下の場所から .env.development.local、.env.development、.env.local、.env の読み込みを試みます。

• 現在の作業ディレクトリ
• services/mcp-server
• リポジトリのルート

テスト

プロトコルとトランスポートのテスト：

npm run test:mcp-server

本番環境との同等性を確認するライブスモークテスト：

npm run test:mcp-server:smoke

スモークテストでは、以下を確認します。

• search_timezones
• answer_time_question
• get_current_time
• get_dst_schedule
• convert_time
• get_overlap_hours
• find_meeting_time
• get_location_by_id

メンテナー向けリリース手順

このパッケージの正式な公開ソースは、現在以下にあります。

• GitHub：https://github.com/hkchao/findtime-mcp-server
• npm：@findtime/mcp-server
• 公式 MCP Registry：https://registry.modelcontextprotocol.io/?q=io.github.hkchao%2Ffindtime-mcp-server

公開とバージョンの更新は、この非公開アプリリポジトリではなく、公開リポジトリから行ってください。

公開リポジトリでの標準的な公開手順：

npm test
npm pack --dry-run
npm publish --access public

このリポジトリで同等のローカル検証を行うコマンドは以下のとおりです。

npm run test:mcp-server
npm run mcp:pack

このリポジトリは、MCP パッケージを当初生成した実装ソースとして扱い、正式な公開リリースソースとしては扱わないでください。

パブリッシャーとツールの安全性

npm パッケージ @findtime/mcp-server と GitHub リポジトリ hkchao/findtime-mcp-server は、findtime.io MCP の配布チャネルです。 製品ドキュメント：https://findtime.io/developers/mcp/

すべてのツールは時刻情報を検索し、会議の候補時刻を提案するか、ヘルプや 診断情報を返します。会議の予約やカレンダーの変更は行いません。各ツールは readOnlyHint: true、destructiveHint: false、idempotentHint: true、 openWorldHint: true を宣言します。読み取り専用とはユーザーに対する操作を指し、 ネットワーク通信が発生しないという意味ではありません。API リクエスト、診断、 任意の利用状況テレメトリーでは、外部サービスに接続します。現在時刻のクエリを 繰り返すと、新しい時刻が返されることがあります。冪等性が示すのは、追加の ドメイン変更がないことです。

API キーの環境変数は、1 つのキーに対する別名の設定項目であり、4 つの別々の 認証情報ではありません。

プライバシー、認証、サービスの制限

プライバシーポリシー：https://findtime.io/privacy/

stdio プロセスはローカルで実行されます。時間関連のツールは、クエリ引数を設定済みの Time API（デフォルトでは https://time-api.findtime.io）に送信します。選択した API キーは Authorization: Bearer ヘッダーを使ってその API に送信され、npm やテレメトリーには送信されません。信頼できる API ホストのみを設定してください。4 つの API キー変数名はエイリアスで、次の順に最初の空でない値が使用されます：FINDTIME_API_KEY、TIME_API_KEY、FINDTIME_MCP_API_KEY、FINDTIME_TIME_API_KEY。

ホスト型の Time API が、API キーの検証、キーごとに設定されたレート制限、クォータを管理します。ラッパーは HTTP 429 を含む上流のエラーを MCP ツールエラーとして転送します。公開 HTTP リスナーを公開したり、独自のローカルレートリミッターを実装したりすることはありません。ヘルプはローカルで提供されます。診断機能は npm のバージョンメタデータも読み取ります。

任意の使用状況テレメトリーは、デフォルトで https://slack.findtime.io/telemetry/usage に送信されます。ラッパーはツール名、結果、クエリテキストの長さ、永続的なインストール／クライアント識別子、バージョン、OS、ロケール、タイムゾーン、レイテンシーを送信します。このテレメトリーイベントには、クエリテキストそのもの、API キー、または呼び出しごとの _endUserId は含まれません。無効にするには FINDTIME_MCP_INSTRUMENTATION_ENABLED=false を設定してください。生成されたインストール識別子は、ユーザーの状態ディレクトリに保存されます。ホストから提供されたアトリビューション識別子は、上記の説明に従って Time API に送信されます。個人を特定できない不透明な値を使用してください。

ライセンス

このリポジトリ内の MCP ラッパーおよびドキュメントは、MIT License のもとでライセンスされています。

このライセンスの対象は、このリポジトリのみです。ホスト型 findtime.io Time API、そのバックエンド実装やデータ、または findtime.io アプリケーション全体に対する権利は付与されません。ホスト型サービスの利用には、引き続き各サービスに適用される規約と API アクセス要件が適用されます。