🌦️ Weekly Weather MCP Server

🌦️ Weekly Weather MCP サーバー

OpenWeatherMap の One Call API 3.0 を使用して、世界中の8日間の天気予報と現在の気象状況を提供する、天気予報用のMCP（Model Context Protocol）サーバーです。

このプロジェクトは、Zippland の以前のプロジェクトを基に、1週間分の予報と、時間帯別の追加データに対応するよう変更を加えています。

特徴

• 🌍 世界中のあらゆる場所の気象状況を照会できます
• 🌤️ 今後48時間の時間別予報
• 📅 朝、午後、夕方のデータを含む詳細な8日間予報（今日と、その後7日間）を提供します
• 🌧️ 天気の概要と降水確率
• 🌡️ 気温、湿度、風速などの詳細な気象情報
• 📍 異なるタイムゾーンでの結果表示に対応
• 🗂️ 個別の設定ファイルは不要です。APIキーは環境変数またはパラメーターで直接渡せます

使用方法

1. One Call API 3.0にアクセスできるOpenWeatherMap APIキーを取得する（無料）

1. OpenWeatherMapにアクセスしてアカウントを登録します
2. 「One Call API 3.0」プランに登録します（1日あたり1,000回のAPI呼び出しが無料です）
3. APIキーが有効になるまで待ちます（最長で1時間ほどかかる場合があります）

One Call API 3.0について

One Call API 3.0では、次のような包括的な気象データを提供します。

• 現在の気象状況
• 1時間分の分単位予報
• 48時間分の時間別予報
• 8日分の日別予報（今日を含む）
• 各国の気象警報
• 過去の気象データ

APIの使用量と制限

• 無料枠：1日あたり1,000回のAPI呼び出し
• デフォルトの上限：1日あたり2,000回のAPI呼び出し（アカウントで変更できます）
• 課金：無料の1日あたり1,000回を超える呼び出しには、OpenWeatherMapの料金体系に従って課金されます
• 使用量の上限：予算を超えないよう、アカウントで呼び出し数の上限を設定できます（無料枠の上限に設定して、費用が発生しないようにすることもできます）
• 上限に達すると、HTTP 429エラーのレスポンスが返されます

注：APIキーが有効になるまで、数分から1時間ほどかかる場合があります。登録直後や新しいキーの生成直後に認証エラーが発生した場合は、しばらく待ってからもう一度お試しください。

2. リポジトリをクローンして依存関係をインストールする

# Clone the repository
git clone https://github.com/rossshannon/weekly-weather-mcp.git
cd weekly-weather-mcp

# Create a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# OR
venv\Scripts\activate  # Windows

# Install dependencies
pip3 install -r requirements.txt

これにより、サーバーと開発ツールの実行に必要な依存関係がすべてインストールされます。

3. サーバーを実行する

APIキーを指定する方法は2つあります。

方法1：環境変数を使用する

# Set environment variables
export OPENWEATHER_API_KEY="your_api_key"  # Linux/Mac
set OPENWEATHER_API_KEY=your_api_key  # Windows

# Run the server
python weather_mcp_server.py

方法2：ツールの呼び出し時に指定する

環境変数を設定せずに直接実行します。

python weather_mcp_server.py

ツールの呼び出し時に、api_key パラメーターを指定する必要があります。

4. MCPクライアントの設定で使用する

次の設定を、MCPに対応したクライアント（Claude Desktop（手順）、Cursorなど）に追加します。

{
  "weather_forecast": {
    "command": "python3",
    "args": [
      "/full_path/weather_mcp_server.py"
    ],
    "env": {
      "OPENWEATHER_API_KEY": "your_openweathermap_key_here"
    },
    "disabled": false,
    "autoApprove": ["get_weather", "get_current_weather"]
  }
}

仮想環境を使用している場合、設定には仮想環境内のPython実行ファイルの絶対パスを指定する必要があります。

{
  "weather_forecast": {
    "command": "/full_path/venv/bin/python3",
    "args": [
      "/full_path/weather_mcp_server.py"
    ],
    "env": {
      "OPENWEATHER_API_KEY": "your_openweathermap_key_here"
    },
    "disabled": false,
    "autoApprove": ["get_weather", "get_current_weather"]
  }
}

5. 利用可能なツール

サーバーは、get_weather と get_current_weather の 2 つのツールを公開します。どちらのツールも同じパラメーターを受け取ります。

• location：文字列で指定する場所の名前です。例：「Beijing」、「New York」、「Tokyo」。ツールが緯度・経度の座標へのジオコーディングを行います。
• api_key：OpenWeatherMap API キーです（省略可能です。指定されていない場合は環境変数から読み取ります）。
• timezone_offset：時間単位のタイムゾーンオフセットです。例：Beijing の場合は 8、New York の場合は -4 です。デフォルトは 0（UTC 時刻）です。返されるデータの時刻は、このタイムゾーンに対応します。

get_weather

場所の現在の天気（今後 48 時間）と、詳細な情報を含む 8 日間の予報など、包括的な天気データを取得します。

返される内容：

• 現在の天気情報
• 今後 48 時間の時間ごとの予報
• 8 日間分（今日とその後 7 日間）の毎日の予報
• 各日の朝（午前 9 時）、午後（午後 3 時）、夜（午後 8 時）のデータポイント
• 天気の概要と降水確率
• 気温、湿度、風速などの詳細な天気情報

次のような用途に最適です：

• 「🏃‍♂️ 今週、ランニングに行くなら何曜日がよさそうですか？」
• 「🪴 今週、庭仕事をするのに最適な夕方はいつですか？」
• 「🪁 近いうちに凧揚げをするなら、いちばん風が強い日はいつですか？」
• 「💧 今週は庭に水やりが必要ですか？それとも雨に任せられますか？」

get_current_weather

指定した場所の現在の天気を取得します。

返される内容：

• get_weather が返すデータのうち、簡略化された一部
• 現在の天気情報のみ（気温、体感温度、天気の状況、湿度、風など）。今後の時間帯の予報データは含まれません。
• 現在の状況だけをすばやく確認するのに便利です。

場所の検索について

location パラメーターは、OpenWeatherMap のジオコーディングを使って、場所の名前を地理座標に変換します。

• 簡単な場所名が使えます：「Paris」、「Tokyo」、「New York」
• 精度を高めるには、国コードを含めてください：「Paris,FR」、「London,GB」、「Portland,US」
• 米国の都市では、州を含めることもできます：「Portland,OR,US」や「Portland,ME,US」
• OpenWeatherMap がジオコーディングできる、地球上のあらゆる場所に対応しています。
• 場所の名前は、内部で緯度・経度の座標に変換されます。

場所が見つからない場合、API はエラーを返します。候補が複数ある場合は、より正確な結果を得るために国コードまたは州コードを追加してください。

使用例

例 1：現在の天気

User: What’s the weather like in New York right now?

AI: Let me check the current weather in New York for you.
[Calling get_current_weather("New York", timezone_offset=-4)]

Current weather in New York: 5°C, few clouds, humidity 42%, wind speed 4.1m/s.

例 2：週間の計画

User: I need to mow my lawn this week in Boston. Which day would be best?

AI: Let me check the weather forecast for Boston to find the best day for lawn mowing.
[Calling get_weather("Boston", timezone_offset=-4)]

Looking at the Boston forecast for the week:
- Today (Monday): Light rain (28% chance), 5°C
- Tuesday: Clear, sunny, 10°C
- Wednesday: Light rain (100% chance), 9°C
- Thursday: Moderate rain (100% chance), 10°C
- Friday: Moderate rain (100% chance), 11°C
- Saturday: Partly cloudy, 13°C
- Sunday: Scattered clouds, 17°C

Tuesday would be your best option for mowing the lawn. It will be clear and sunny with no chance of rain, and the temperature will be comfortable at around 10°C.

この MCP サーバーをほかのサーバーと組み合わせて、複数ステップのワークフローを実行できます。たとえば、天気を確認したあと、Claude にその予定をカレンダーのイベントとして追加して、予定を忘れないようにすることもできます。

トラブルシューティング

API キーに関する問題

「Invalid API key」または認証エラーが発生した場合：

1. 「One Call API 3.0」プランに登録していることを確認してください。アカウントを有効にするにはデビットカードまたはクレジットカードが必要ですが、無料枠の上限を超えた場合にのみ課金されます。
2. API キーの有効化には、最大 1 時間かかる場合があることにご注意ください。
3. 環境変数で OPENWEATHER_API_KEY が正しく設定されていることを確認するか、ツールの呼び出し時に正しい api_key パラメーターを指定していることを確認してください。

その他の一般的な問題

• 「Location not found」エラー：

  • 地名のスペルミスがないか確認してください
  • 非常に小さな場所や遠隔地の場所は、OpenWeatherMap のデータベースに登録されていない場合があります

• 誤った場所が返される場合：

  • より正確な都市名を使うか、国コードを追加してください。例：「Beijing,CN」または「Porto,PT」
  • 米国の一般的な名前の都市では、州を指定してください：「Springfield,IL,US」または「Portland,OR,US」
  • 異なる国に同じ名前の都市がある場合は、国コードと該当する場合は州を必ず含めてください：「Paris,FR」はフランスのパリ、「Paris,TX,US」は米国テキサス州のパリです。

• レート制限（429 エラー）：API 呼び出しの上限を超えています。OpenWeatherMap アカウントの設定を確認してください。

開発とテスト

テスト

このプロジェクトには、MCP サーバーの機能を検証するための単体テスト、統合テスト、モッククライアントのテストファイルが含まれています。サーバーが Claude Desktop、Cursor、その他の MCP クライアントで正しく動作することは、手動でテスト済みです。

クライアントの手動テスト

Claude Desktop やその他の MCP クライアントでサーバーを設定する前に、付属のテストスクリプトを使って API キーとインストールを確認できます。

1. OpenWeatherMap API キーを設定します：

   export OPENWEATHER_API_KEY="your_api_key"
   

2. テストクライアントを実行します：

   python3 test_mcp_client.py
   

テストスクリプトは天気関数を直接呼び出し、ニューヨークの現在の天気を確認して結果を表示します。これにより、次の項目を確認できます。

1. API キーが正しく機能している
2. OpenWeatherMap API にアクセスできる
3. 天気データ関数が動作している

テストで現在の天気データが表示されたら、Claude Desktop、Cursor、その他の MCP クライアントでサーバーを設定する準備ができています。

自動テスト

リポジトリには、次の項目を行う単体テストと統合テストのファイルが含まれています。

• API キーの処理と検証をテストする
• データの解析とフォーマットを検証する
• API 障害時のエラー処理を確認する
• 公開されている両方の MCP ツール、get_weather と get_current_weather をテストする

これらのテストを実行するには、すべての依存関係をインストールした適切な開発環境が必要です。今後の開発の参考として提供されています。

自動テストを実行するには：

# Run unit tests
python test_weather_mcp.py

# Run integration tests
python test_mcp_integration.py

テストでは、OpenWeatherMap API からの応答をシミュレートするサンプル API 応答（test_weather_response.json）を使用するため、API キーやインターネット接続なしで実行できます。

これらのテストは、今後の開発の参考として、また変更後も MCP サーバーが引き続き正しく機能することを確認するために提供されています。

クレジット

このプロジェクトは、Zippland によるオリジナルの Weather MCP をベースにしています。変更点は次のとおりです。

• OpenWeatherMap One Call API 3.0 との連携
• 予報期間を 2 日間から 8 日間（今日＋7 日間）に拡張
• 各日の午前、午後、夕方のデータポイントを追加
• 今後 48 時間の時間ごとの予報
• 天気の概要、風速、降水確率を追加
• 単体テスト、統合テスト、モッククライアントのテストファイル