TimezoneToolkit MCP Server

利用可能なツール

ツール	説明
convert_time	あるタイムゾーンの時刻を別のタイムゾーンに変換します
get_current_time	指定したタイムゾーンの現在時刻を取得します
calculate_sunrise_sunset	特定の場所と日付の日の出、日の入り、薄明の時刻を計算します
calculate_moon_phase	特定の日付の月相を計算します
calculate_timezone_difference	2 つのタイムゾーン間の時差を計算します
list_timezones	利用可能な IANA タイムゾーンを一覧表示します。地域による絞り込みも可能です
calculate_countdown	特定の日付／イベントまでの残り時間を計算します
calculate_business_days	2 つの日付の間の営業日数を計算します（土日を除く）
format_date	さまざまな形式で日付をフォーマットします

🌟 機能

🕒 基本的なタイムゾーン変換

• 任意の IANA タイムゾーン間で時刻を変換します
• 任意のタイムゾーンの現在時刻を取得します
• さまざまな形式（短縮、中程度、完全）で時刻をフォーマットします
• 時差を時間／分で計算します
• 利用可能な IANA タイムゾーンを一覧表示します

🌅 日の出／日の入りと天文計算

• 任意の場所の日の出と日の入りの時刻を計算します
• 薄明の時刻（市民薄明、航海薄明、天文薄明）も含めます
• 任意の場所／日付の日照時間を計算します
• 任意の日付の月相を計算します

📅 日付と時刻のユーティリティ

• さまざまな形式（短縮、中程度、完全、ISO、相対）で日付をフォーマットします
• 日付間の営業日数を計算します
• 将来のイベントまでのカウントダウンタイマーを作成します
• 複数のロケールとタイムゾーンに対応します

💻 インストール

前提条件

• Node.js 18.x 以降 — TimezoneToolkit MCP サーバーを正常に実行するには、Node.js 18 以降が必要です。

セットアップ

Node.js npx を使用して TimezoneToolkit MCP サーバーを実行するには、次のコマンドを使用します。

npx -y @cicatriz/timezone-toolkit@latest

クライアント別のインストール

Cursor

このサーバーを Cursor IDE に追加するには：

1. Cursor の Settings > MCP に移動します
2. • Add new Global MCP Server をクリックします
3. 次の設定をグローバルな .cursor/mcp.json ファイルに追加します：

{
  "mcpServers": {
    "timezone-toolkit": {
      "command": "npx",
      "args": [
        "-y",
        "@cicatriz/timezone-toolkit"
      ]
    }
  }
}

詳細については、Cursor のドキュメントを参照してください。

Windsurf

Cascade で MCP を設定するには、Windsurf - Settings > Advanced Settings または Command Palette > Open Windsurf Settings Page に移動します。

Cascade セクションまでスクロールし、TimezoneToolkit MCP サーバーを mcp_config.json に直接追加します：

{
  "mcpServers": {
    "timezone-toolkit": {
      "command": "npx",
      "args": [
        "-y",
        "@cicatriz/timezone-toolkit"
      ]
    }
  }
}

Cline

Cline MCP Server の設定から、次の JSON を cline_mcp_settings.json に手動で追加します：

{
  "mcpServers": {
    "timezone-toolkit": {
      "command": "npx",
      "args": [
        "-y",
        "@cicatriz/timezone-toolkit"
      ]
    }
  }
}

Roo Code

Roo Code の設定で Edit MCP Settings をクリックするか、VS Code のコマンドパレットから Roo Code: Open MCP Config コマンドを使用して、MCP 設定にアクセスします：

{
  "mcpServers": {
    "timezone-toolkit": {
      "command": "npx",
      "args": [
        "-y",
        "@cicatriz/timezone-toolkit"
      ]
    }
  }
}

Claude

次の内容を claude_desktop_config.json ファイルに追加します：

{
  "mcpServers": {
    "timezone-toolkit": {
      "command": "npx",
      "args": [
        "-y",
        "@cicatriz/timezone-toolkit"
      ]
    }
  }
}

詳細については、Claude Desktop のドキュメントを参照してください。

CLI

次のコマンドを実行して、CLI として実行することもできます：

npx -y @cicatriz/timezone-toolkit@latest

別のインストール方法

npm からインストール

# Install globally from npm
npm install -g @cicatriz/timezone-toolkit

# Run the server
timezone-toolkit

手動インストール

# Clone the repository
git clone https://github.com/Cicatriiz/timezone-toolkit.git
cd timezone-toolkit

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
node dist/index.js

💬 Claude Desktop での使用方法

インストール後、Claude Desktop で TimezoneToolkit を使用できます：

1. Claude Desktop を開きます
2. 新しい会話を開始します
3. ハンマーアイコンをクリックして、利用可能なツールを確認します
4. TimezoneToolkit のツールを選択します

🔗 API アクセス

TimezoneToolkit は、Claude Desktop を使わずに機能へアクセスできる RESTful API も提供しています：

API サーバーの起動

# Using npm
npm install -g @cicatriz/timezone-toolkit
node server.js

API サーバーは http://localhost:3000 で利用できます

API エンドポイント

• GET /api/tools - 利用可能なすべてのツールを一覧表示します
• POST /api/convert-time - タイムゾーン間で時刻を変換します
• POST /api/current-time - 指定したタイムゾーンの現在時刻を取得します
• POST /api/sunrise-sunset - 日の出・日の入りの時刻を計算します
• POST /api/moon-phase - 月相を計算します
• POST /api/timezone-difference - タイムゾーン間の時差を計算します
• POST /api/list-timezones - 利用可能なタイムゾーンを一覧表示します
• POST /api/countdown - 日付までのカウントダウンを計算します
• POST /api/business-days - 日付間の営業日数を計算します
• POST /api/format-date - 日付をフォーマットします

API ドキュメントの詳細については、API README を参照してください。

クエリの例

• 「東京の現在時刻は何時ですか？」
• 「ニューヨーク時間の午後 3 時をロンドン時間に変換して」
• 「サンフランシスコの日の出は明日何時ですか？」
• 「パリの日の入りは今日何時ですか？」
• 「現在の月相は何ですか？」
• 「ニューヨークと東京の時差はどれくらいですか？」
• 「ヨーロッパのタイムゾーン一覧を表示して」
• 「3 月 1 日から 4 月 15 日までの営業日は何日ありますか？」
• 「今日の日付をフランス語ロケールでフォーマットして」
• 「大晦日まであとどれくらいですか？」

🔧 利用可能なツール

1. convert_time

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

パラメーター：

• time（任意）：変換する時刻（ISO 文字列または自然言語）。指定しない場合は現在時刻が既定値になります。
• fromTimezone：変換元の IANA タイムゾーン名（例：'America/New_York'）
• toTimezone：変換先の IANA タイムゾーン名（例：'Europe/London'）
• format（任意）：出力形式（'short'、'medium'、'full'）。既定値は 'medium' です。

例：

{
  "time": "2023-12-25T14:30:00",
  "fromTimezone": "America/New_York",
  "toTimezone": "Asia/Tokyo",
  "format": "full"
}

応答：

{
  "originalTime": "2023-12-25T14:30:00.000-05:00",
  "convertedTime": "Tuesday, December 26, 2023, 4:30:00 AM Japan Standard Time",
  "fromTimezone": "America/New_York",
  "toTimezone": "Asia/Tokyo",
  "timeDifference": "+14 hours"
}

2. get_current_time

指定したタイムゾーンの現在時刻を取得します。

パラメーター：

• timezone：IANA タイムゾーン名（例：'Asia/Tokyo'）
• format（任意）：出力形式（'short'、'medium'、'full'）。既定値は 'medium' です。

例：

{
  "timezone": "Europe/London",
  "format": "full"
}

応答：

{
  "currentTime": "Monday, March 25, 2025, 10:15:30 PM British Summer Time",
  "timezone": "Europe/London",
  "utcOffset": "+01:00"
}

3. calculate_sunrise_sunset

指定した場所と日付の日の出、日の入り、薄明の時刻を計算します。

パラメーター：

• date（任意）：計算する日付（ISO 文字列または自然言語）。指定しない場合は現在の日付が既定値になります。
• latitude：場所の緯度（-90～90）
• longitude：場所の経度（-180～180）
• timezone（任意）：IANA タイムゾーン名（例：'Europe/Paris'）。既定値は UTC です。

例：

{
  "date": "2023-06-21",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "timezone": "America/Los_Angeles"
}

応答：

{
  "date": "2023-06-21",
  "sunrise": "05:48:11 AM",
  "sunset": "08:35:13 PM",
  "civilTwilight": {
    "dawn": "05:17:22 AM",
    "dusk": "09:06:02 PM"
  },
  "nauticalTwilight": {
    "dawn": "04:38:43 AM",
    "dusk": "09:44:41 PM"
  },
  "astronomicalTwilight": {
    "dawn": "03:52:50 AM",
    "dusk": "10:30:34 PM"
  },
  "dayLength": "14 hours 47 minutes",
  "timezone": "America/Los_Angeles"
}

4. calculate_moon_phase

指定した日付の月相を計算します。

パラメーター：

• date（任意）：計算する日付（ISO 文字列または自然言語）。指定しない場合は現在の日付が既定値になります。
• timezone（任意）：IANA タイムゾーン名（例：'Europe/Paris'）。既定値は UTC です。

例：

{
  "date": "2023-01-06",
  "timezone": "UTC"
}

応答：

{
  "date": "2023-01-06",
  "phase": 0.998,
  "phaseName": "Full Moon",
  "illumination": 0.997,
  "timezone": "UTC"
}

5. calculate_timezone_difference

2 つのタイムゾーン間の時差を計算します。

パラメーター：

• fromTimezone：変換元の IANA タイムゾーン名（例：'America/New_York'）
• toTimezone：変換先の IANA タイムゾーン名（例：'Europe/London'）

例：

{
  "fromTimezone": "America/New_York",
  "toTimezone": "Asia/Tokyo"
}

応答：

{
  "fromTimezone": "America/New_York",
  "toTimezone": "Asia/Tokyo",
  "timeDifference": "+14 hours",
  "currentTimeFrom": "3/25/2025, 6:15 PM",
  "currentTimeTo": "3/26/2025, 8:15 AM",
  "hoursDifference": 14,
  "minutesDifference": 0,
  "totalMinutesDifference": 840,
  "direction": "ahead"
}

6. list_timezones

利用可能な IANA タイムゾーンを一覧表示します。地域で絞り込むこともできます。

パラメーター：

• region（任意）：地域でタイムゾーンを絞り込みます（例：'America'、'Europe'、'Asia'）

例：

{
  "region": "Europe"
}

応答：

{
  "timezones": [
    {
      "timezone": "Europe/Amsterdam",
      "currentTime": "3/25/2025, 11:15 PM",
      "offset": "+02:00"
    },
    {
      "timezone": "Europe/Berlin",
      "currentTime": "3/25/2025, 11:15 PM",
      "offset": "+02:00"
    },
    // Additional European timezones...
  ],
  "count": 7,
  "region": "Europe"
}

7. calculate_countdown

指定した日付またはイベントまでの残り時間を計算します。

パラメーター：

• targetDate：目標の日付／時刻（ISO 文字列または自然言語）
• timezone（任意）：IANA タイムゾーン名（例：'America/New_York'）。指定しない場合はシステムのタイムゾーンが既定値になります。
• title（任意）：イベントのタイトルまたは名前

例：

{
  "targetDate": "2025-12-31T23:59:59",
  "timezone": "UTC",
  "title": "New Year's Eve"
}

応答：

{
  "title": "New Year's Eve",
  "targetDate": "2025-12-31T23:59:59.000Z",
  "formattedTargetDate": "Wednesday, December 31, 2025, 11:59:59 PM GMT",
  "currentDate": "2025-03-25T18:15:30.000Z",
  "timezone": "UTC",
  "isPast": false,
  "countdown": "9 months, 6 days, 5 hours, 44 minutes, 29 seconds",
  "remaining": {
    "years": 0,
    "months": 9,
    "days": 6,
    "hours": 5,
    "minutes": 44,
    "seconds": 29,
    "totalDays": 281,
    "totalHours": 6749,
    "totalMinutes": 404969,
    "totalSeconds": 24298169
  }
}

8. calculate_business_days

2 つの日付の間の営業日数を計算します（週末を除きます）。

パラメーター：

• startDate：開始日（ISO 文字列または自然言語）
• endDate：終了日（ISO 文字列または自然言語）
• timezone（任意）：IANA タイムゾーン名（例：'America/New_York'）。デフォルトはシステムのタイムゾーンです。
• excludeHolidays（任意）：一般的な祝日（米国の祝日のみ）を除外するかどうか。デフォルトは false です。

例：

{
  "startDate": "2023-05-01",
  "endDate": "2023-05-31",
  "timezone": "UTC",
  "excludeHolidays": true
}

レスポンス：

{
  "startDate": "2023-05-01",
  "endDate": "2023-05-31",
  "businessDays": 22,
  "calendarDays": 31,
  "weekendDays": 8,
  "holidaysExcluded": 1,
  "timezone": "UTC",
  "businessDatesIncluded": ["2023-05-01", "2023-05-02", "2023-05-03", "2023-05-04", "2023-05-05", "2023-05-08", "2023-05-09", "2023-05-10", "2023-05-11", "2023-05-12", "2023-05-15", "2023-05-16", "2023-05-17", "2023-05-18", "2023-05-19", "2023-05-22", "2023-05-23", "2023-05-24", "2023-05-25", "2023-05-26", "2023-05-30", "2023-05-31"]
}

9. format_date

日付をさまざまな形式でフォーマットします。

パラメーター：

• date：フォーマットする日付（ISO 文字列または自然言語）。デフォルトは現在の日付です。
• timezone（任意）：IANA タイムゾーン名（例：'America/New_York'）。デフォルトはシステムのタイムゾーンです。
• format（任意）：出力形式（'short'、'medium'、'full'、'iso'、'relative'）。デフォルトは 'medium' です。
• locale（任意）：フォーマットに使用するロケール（例：'en-US'、'fr'、'de'）。デフォルトは 'en-US' です。

例：

{
  "date": "2023-12-25",
  "timezone": "Europe/Paris",
  "format": "full",
  "locale": "fr"
}

レスポンス：

{
  "originalDate": "2023-12-25",
  "parsedDate": "2023-12-25T00:00:00.000+01:00",
  "formattedDate": "lundi 25 décembre 2023",
  "formattedTime": "00:00:00 heure normale d'Europe centrale",
  "formattedDateTime": "lundi 25 décembre 2023 à 00:00:00 heure normale d'Europe centrale",
  "dayOfWeek": "lundi",
  "dayOfMonth": 25,
  "month": "décembre",
  "year": 2023,
  "timezone": "Europe/Paris",
  "locale": "fr",
  "format": "full"
}

💬 Claude Desktop でのクエリ例

• 「東京の現在時刻は何時ですか？」
• 「ニューヨーク時間の午後 3 時をロンドン時間に変換してください」
• 「サンフランシスコでは明日の日の出は何時ですか？」
• 「パリでは今日の日没は何時ですか？」
• 「現在の月相は何ですか？」
• 「ニューヨークと東京の時差はどれくらいですか？」
• 「ヨーロッパのタイムゾーンの一覧を表示してください」
• 「3 月 1 日から 4 月 15 日までの営業日は何日ありますか？」
• 「今日の日付をフランス語のロケールでフォーマットしてください」
• 「大晦日まであとどれくらいですか？」

💻 技術的な詳細

アーキテクチャ

TimezoneToolkit は、Claude Desktop とシームレスに統合できる Model Context Protocol（MCP）仕様に基づいて構築されています。サーバーは TypeScript で実装されており、次のアーキテクチャを使用します。

• コアサービス：タイムゾーン変換、天文計算、日付フォーマットを実装します
• MCP サーバー：Claude Desktop からの JSON-RPC リクエストを処理します
• ユーティリティ関数：日付と時刻の操作を支援する関数を提供します
• テストフレームワーク：機能を検証するための包括的なテストスクリプトが含まれています

依存関係

• Luxon - すべての日付と時刻の処理およびタイムゾーン操作に使用します
• SunCalc - 日の出・日の入りと天文計算に使用します
• @modelcontextprotocol/sdk - MCP サーバーの実装に使用します

要件

• Node.js 18.x 以上
• npm 9.x 以上
• Claude Desktop（最新バージョン）

📝 コントリビューション

コントリビューションを歓迎します！お気軽に Pull Request を送信してください。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add some amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. Pull Request を作成します

🧪 テスト

TimezoneToolkit には、MCP サーバーの機能を検証するための包括的なテストスクリプトが含まれています。このテストスクリプトを使用して、ローカルビルドやバージョンフラグのテスト、利用可能なすべてのツールの一覧表示、特定のツールのテスト、公開後の npm パッケージのテストを実行できます。

テストの実行

# Test the local build (default)
node test-server.js

# Test a specific tool
node test-server.js --tool=calculate_sunrise_sunset

# List all available tools
node test-server.js --list

# Test the version flag
node test-server.js --test-version

# Test the published npm package (after publishing)
node test-server.js --npm

テストスクリプトは、レスポンス形式が正しいか、コンテンツが有効な JSON かどうかなど、テスト結果の詳細情報を出力します。

出力例

Testing local build...
Running: node /path/to/timezone-toolkit/dist/index.js

Sending request: {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_current_time",
    "arguments": {
      "timezone": "America/New_York"
    }
  }
}

Response: {
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"currentTime\": \"Mar 25, 2025, 9:54 PM\",\n  \"timezone\": \"America/New_York\",\n  \"utcOffset\": \"-04:00\"\n}"
      }
    ]
  },
  "jsonrpc": "2.0",
  "id": 1
}
✅ Response format is correct (has content array)
✅ Content is valid JSON: {
  currentTime: 'Mar 25, 2025, 9:54 PM',
  timezone: 'America/New_York',
  utcOffset: '-04:00'
}

✅ Test completed successfully!

🐛 トラブルシューティング

よくある問題

1. ツールが Claude Desktop に表示されない

   • Claude Desktop の設定でサーバーが正しく設定されていることを確認してください
   • index.js ファイルへのパスが正しいことを確認してください
   • Claude Desktop を再起動してください

2. タイムゾーンの計算が正しくない

   • 有効な IANA タイムゾーン名を使用していることを確認してください（'EST' ではなく 'America/New_York' など）
   • 計算に影響する可能性がある夏時間への移行を確認してください

3. 日の出・日の入りの計算が機能しない

   • 緯度と経度の値が有効であることを確認してください（緯度は -90～90、経度は -180～180）
   • 極端に北または南に位置する場所では、日の出や日の入りがない期間が生じる場合があります

🔒 プライバシーとセキュリティ

TimezoneToolkit はすべてのデータをローカルで処理し、外部サーバーに情報を送信することはありません。タイムゾーンのデータやクエリは、お使いのデバイス内でプライベートに保たれます。

📃 ライセンス

ISC

👨‍💻 作者

Cicatriz