Weather MCP Server

Weather MCP サーバー

mcp-name: io.github.isdaniel/mcp_weather_server

Open-Meteo API を使用して気象情報を提供する Model Context Protocol（MCP）サーバーです。このサーバーは、標準の stdio、HTTP Server-Sent Events（SSE）、Web ベースの統合向けの新しい Streamable HTTP プロトコルなど、複数のトランスポートモードに対応しています。

機能

気象と大気質

• 詳細な指標を含む現在の気象情報を取得できます：
  • 気温、湿度、露点
  • 風速、風向、突風
  • 降水量（雨／雪）と確率
  • 気圧と雲量
  • UV インデックスと視程
  • 体感気温
  • 日の出と日の入りの時刻（現地時間）
• 時間ごとの詳細情報と毎日の日の出・日の入り時刻を含む、指定期間の気象データを取得できます
• 次の情報を含む大気質情報を取得できます：
  • PM2.5 および PM10 粒子状物質
  • オゾン、二酸化窒素、一酸化炭素
  • 二酸化硫黄、アンモニア、粉じん
  • エアロゾル光学的厚さ
  • 健康に関する注意事項と推奨事項

時刻とタイムゾーン

• 任意のタイムゾーンの現在の日付と時刻を取得できます
• タイムゾーン間で時刻を変換できます
• タイムゾーン情報を取得できます

トランスポートモード

• 複数のトランスポートモード：
  • stdio - デスクトップクライアント向けの標準 MCP（Claude Desktop など）
  • SSE - Web アプリケーション向けの Server-Sent Events
  • streamable-http - ステートフル／ステートレスのオプションを備えた最新の MCP Streamable HTTP プロトコル
• Starlette 統合による RESTful API エンドポイント

インストール

Smithery 経由でのインストール

Smithery 経由で Weather MCP サーバーを自動的にインストールするには：

npx -y @smithery/cli install @isdaniel/mcp_weather_server

標準インストール（Claude Desktop などの MCP クライアント向け）

このパッケージは pip を使用してインストールできます：

pip install mcp_weather_server

MCP クライアント向けの手動設定

このサーバーは、設定を cline_mcp_settings.json ファイルに追加して手動でインストールするように設計されています。

1. cline_mcp_settings.json ファイルの mcpServers オブジェクトに、次のエントリーを追加します：

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": [
        "-m",
        "mcp_weather_server"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}

2. cline_mcp_settings.json ファイルを保存します。

HTTP サーバーのインストール（Web アプリケーション向け）

HTTP SSE または Streamable HTTP に対応するには、追加の依存関係が必要です：

pip install mcp_weather_server starlette uvicorn

サーバーモード

この MCP サーバーは、統合された単一のサーバーで stdio、SSE、streamable-http モードに対応しています：

モードの比較

機能	stdio	SSE	streamable-http
用途	デスクトップ MCP クライアント	Web アプリケーション（レガシー）	Web アプリケーション（最新）
プロトコル	標準入出力ストリーム	Server-Sent Events	MCP Streamable HTTP
セッション管理	該当なし	ステートフル	ステートフルまたはステートレス
エンドポイント	該当なし	/sse、/messages/	/mcp（単一）
最適な用途	Claude Desktop、Cline	ブラウザベースのアプリ	最新の Web アプリ、API
状態オプション	該当なし	ステートフルのみ	ステートフルまたはステートレス

1. 標準 MCP モード（デフォルト）

標準モードは stdio 経由で通信し、Claude Desktop などの MCP クライアントと互換性があります。

# Default mode (stdio)
python -m mcp_weather_server

# Explicitly specify stdio mode
python -m mcp_weather_server.server --mode stdio

2. HTTP SSE モード（ウェブアプリケーション）

SSE モードでは、Server-Sent Events を介して MCP 機能を提供する HTTP サーバーを実行し、ウェブアプリケーションから利用できるようにします。

# Start SSE server on default host/port (0.0.0.0:8080)
python -m mcp_weather_server --mode sse

# Specify custom host and port
python -m mcp_weather_server --mode sse --host localhost --port 3000

# Enable debug mode
python -m mcp_weather_server --mode sse --debug

SSE エンドポイント：

• GET /sse - MCP 通信用の SSE エンドポイント
• POST /messages/ - MCP リクエストを送信するためのメッセージエンドポイント

3. Streamable HTTP モード（最新の MCP プロトコル）

streamable-http モードでは、単一の /mcp エンドポイントを使用する新しい MCP Streamable HTTP プロトコルを実装します。このモードは、ステートフル（デフォルト）とステートレスの両方の操作をサポートします。

# Start streamable HTTP server on default host/port (0.0.0.0:8080)
python -m mcp_weather_server --mode streamable-http

# Specify custom host and port
python -m mcp_weather_server --mode streamable-http --host localhost --port 3000

# Enable stateless mode (creates fresh transport per request, no session tracking)
python -m mcp_weather_server --mode streamable-http --stateless

# Enable debug mode
python -m mcp_weather_server --mode streamable-http --debug

Streamable HTTP の機能：

• ステートフルモード（デフォルト）：セッション ID を使用して、リクエスト間のセッション状態を維持します
• ステートレスモード：セッション追跡を行わず、リクエストごとに新しいトランスポートを作成します
• 単一のエンドポイント：すべての MCP 通信は /mcp を介して行われます
• 最新のプロトコル：最新の MCP Streamable HTTP 仕様を実装しています

Streamable HTTP エンドポイント：

• POST /mcp - すべての MCP 通信（initialize、tools/list、tools/call など）に使用する単一のエンドポイント

コマンドラインオプション：

--mode {stdio,sse,streamable-http}  Server mode: stdio (default), sse, or streamable-http
--host HOST                          Host to bind to (HTTP modes only, default: 0.0.0.0)
--port PORT                          Port to listen on (HTTP modes only, default: 8080)
--stateless                          Run in stateless mode (streamable-http only)
--debug                              Enable debug mode

SSE の使用例：

// Connect to SSE endpoint
const eventSource = new EventSource('http://localhost:8080/sse');

// Send MCP tool request
fetch('http://localhost:8080/messages/', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'tool_call',
    tool: 'get_weather',
    arguments: { city: 'Tokyo' }
  })
});

Streamable HTTP の使用例：

// Initialize session and call tool using Streamable HTTP protocol
async function callWeatherTool() {
  const response = await fetch('http://localhost:8080/mcp', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      method: 'tools/call',
      params: {
        name: 'get_current_weather',
        arguments: { city: 'Tokyo' }
      },
      id: 1
    })
  });

  const result = await response.json();
  console.log(result);
}

設定

このサーバーでは API キーは必要ありません。無料のオープンソースである Open-Meteo API を使用します。

使用方法

このサーバーでは、天気や時刻に関する操作を行うためのツールをいくつか提供します。

利用可能なツール

天気ツール

1. get_current_weather - 詳細な指標を含む、都市の現在の天気を取得します
2. get_weather_by_datetime_range - 時間ごとの詳細を含む、指定期間の天気データを取得します
3. get_weather_details - 構造化 JSON データとして詳細な天気情報を取得します

大気質ツール

4. get_air_quality - 汚染物質のレベルと健康に関するアドバイスを含む、大気質情報を取得します
5. get_air_quality_details - 構造化 JSON として詳細な大気質データを取得します

時刻・タイムゾーンツール

6. get_current_datetime - 任意のタイムゾーンの現在時刻を取得します
7. get_timezone_info - タイムゾーン情報を取得します
8. convert_time - タイムゾーン間で時刻を変換します

ツールの詳細

get_current_weather

指定された都市の現在の天気について、拡充された指標を含む詳細情報を取得します。

パラメーター：

• city（string、必須）：都市名（英語名のみ）

**戻り値：**次の情報を含む詳細な天気データ：

• 気温と体感温度
• 湿度、露点
• 風速、風向（方位）、突風
• 降水量（雨／雪）の詳細と降水確率
• 気圧と雲量
• 警告レベル付きの UV インデックス
• 視程

応答例：

The weather in Tokyo is Mainly clear with a temperature of 22.5°C (feels like 21.0°C),
relative humidity at 65%, and dew point at 15.5°C. Wind is blowing from the NE at 12.5 km/h
with gusts up to 18.5 km/h. Atmospheric pressure is 1013.2 hPa with 25% cloud cover.
UV index is 5.5 (Moderate). Visibility is 10.0 km.

get_weather_by_datetime_range

指定した都市の開始日から終了日までの、詳細な指標を含む時間ごとの天気情報を取得します。

パラメーター：

• city（string、必須）：都市名（英語名のみ）
• start_date（string、必須）：開始日（形式：YYYY-MM-DD、ISO 8601）
• end_date（string、必須）：終了日（形式：YYYY-MM-DD、ISO 8601）

**戻り値：**次の情報を含む詳細な天気分析：

• 拡充されたすべての指標を含む、時間ごとの天気データ
• 気温の推移（最高、最低、平均）
• 降水量のパターンと降水確率
• 風の状態の評価
• UV インデックスの推移
• 天気に関する警告と推奨事項

応答例：

[Analysis of weather trends over 2024-01-01 to 2024-01-07]
- Temperature ranges from 5°C to 15°C
- Precipitation expected on Jan 3rd and 5th (60% probability)
- Wind speeds averaging 15 km/h from SW direction
- UV index moderate (3-5) throughout the period
- Recommendation: Umbrella needed for midweek

get_weather_details

指定した都市の詳細な天気情報を、プログラムで利用できる構造化 JSON データとして取得します。

パラメーター：

• city（string、必須）：都市名（英語名のみ）

**戻り値：**処理や分析に適した、すべての天気指標を含む生の JSON データ

get_air_quality

指定した都市の現在の大気質情報を、汚染物質の濃度と健康に関する注意事項とともに取得します。

パラメーター：

• city（string、必須）：都市名（英語表記のみ）
• variables（array、任意）：取得する特定の汚染物質。選択肢：
  • pm10 - 粒子状物質 ≤10μm
  • pm2_5 - 粒子状物質 ≤2.5μm
  • carbon_monoxide - CO 濃度
  • nitrogen_dioxide - NO2 濃度
  • ozone - O3 濃度
  • sulphur_dioxide - SO2 濃度
  • ammonia - NH3 濃度
  • dust - 粉じん粒子の濃度
  • aerosol_optical_depth - 大気の濁度

戻り値： 以下を含む包括的な大気質レポート：

• 単位付きの現在の汚染物質濃度
• 大気質の分類（良好／普通／健康に悪影響／危険）
• 一般の人々向けの健康に関する推奨事項
• 高感受性グループに対する具体的な警告
• WHO および EPA の基準との比較

応答例：

Air quality in Beijing (lat: 39.90, lon: 116.41):
PM2.5: 45.3 μg/m³ (Unhealthy for Sensitive Groups)
PM10: 89.2 μg/m³ (Moderate)
Ozone (O3): 52.1 μg/m³
Nitrogen Dioxide (NO2): 38.5 μg/m³
Carbon Monoxide (CO): 420.0 μg/m³

Health Advice: Sensitive groups (children, elderly, people with respiratory conditions)
should limit outdoor activities.

get_air_quality_details

プログラムによる分析向けに、構造化された JSON データとして詳細な大気質情報を取得します。

パラメーター：

• city（string、必須）：都市名（英語表記のみ）
• variables（array、任意）：取得する特定の汚染物質（get_air_quality と同じ選択肢）

戻り値： 大気質の全指標と時間ごとのデータを含む生の JSON データ

get_current_datetime

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

パラメーター：

• timezone_name（string、必須）：IANA タイムゾーン名（例：'America/New_York'、'Europe/London'）。タイムゾーンが指定されていない場合は UTC を使用します。

戻り値： 指定したタイムゾーンの現在の日付と時刻

例：

{
  "timezone": "America/New_York",
  "current_time": "2024-01-15T14:30:00-05:00",
  "utc_time": "2024-01-15T19:30:00Z"
}

get_timezone_info

特定のタイムゾーンに関する情報を取得します。

パラメーター：

• timezone_name（string、必須）：IANA タイムゾーン名

戻り値： オフセットや夏時間の情報など、タイムゾーンの詳細

convert_time

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

パラメーター：

• time_str（string、必須）：変換する時刻（ISO 形式）
• from_timezone（string、必須）：変換元のタイムゾーン
• to_timezone（string、必須）：変換先のタイムゾーン

戻り値： 変換先のタイムゾーンでの変換後の時刻

MCP クライアントの使用例

Claude Desktop または MCP クライアントでの使用

<use_mcp_tool>
<server_name>weather</server_name>
<tool_name>get_current_weather</tool_name>
<arguments>
{
  "city": "Tokyo"
}
</arguments>
</use_mcp_tool>

<use_mcp_tool>
<server_name>weather</server_name>
<tool_name>get_weather_by_datetime_range</tool_name>
<arguments>
{
  "city": "Paris",
  "start_date": "2024-01-01",
  "end_date": "2024-01-07"
}
</arguments>
</use_mcp_tool>

<use_mcp_tool>
<server_name>weather</server_name>
<tool_name>get_current_datetime</tool_name>
<arguments>
{
  "timezone_name": "Europe/Paris"
}
</arguments>
</use_mcp_tool>

<use_mcp_tool>
<server_name>weather</server_name>
<tool_name>get_air_quality</tool_name>
<arguments>
{
  "city": "Beijing"
}
</arguments>
</use_mcp_tool>

<use_mcp_tool>
<server_name>weather</server_name>
<tool_name>get_air_quality</tool_name>
<arguments>
{
  "city": "Los Angeles",
  "variables": ["pm2_5", "pm10", "ozone"]
}
</arguments>
</use_mcp_tool>

Web 連携（SSE モード）

SSE モードで実行している場合、天気サーバーを Web アプリケーションと連携できます。

HTML/JavaScript の例

<!DOCTYPE html>
<html>
<head>
    <title>Weather MCP Client</title>
</head>
<body>
    <div id="weather-data"></div>
    <script>
        // Connect to SSE endpoint
        const eventSource = new EventSource('http://localhost:8080/sse');

        eventSource.onmessage = function(event) {
            const data = JSON.parse(event.data);
            document.getElementById('weather-data').innerHTML = JSON.stringify(data, null, 2);
        };

        // Function to get weather
        async function getWeather(city) {
            const response = await fetch('http://localhost:8080/messages/', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({
                    jsonrpc: '2.0',
                    method: 'tools/call',
                    params: {
                        name: 'get_current_weather',
                        arguments: { city: city }
                    },
                    id: 1
                })
            });
        }

        // Example: Get weather for Tokyo
        getWeather('Tokyo');

        // Example: Get air quality
        async function getAirQuality(city) {
            const response = await fetch('http://localhost:8080/messages/', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({
                    jsonrpc: '2.0',
                    method: 'tools/call',
                    params: {
                        name: 'get_air_quality',
                        arguments: { city: city }
                    },
                    id: 2
                })
            });
        }

        getAirQuality('Beijing');
    </script>
</body>
</html>

Docker デプロイ

このプロジェクトは Docker Hub で Docker イメージとして提供されており、簡単にデプロイできる設定も含まれています。

Docker Hub ですぐに開始

Docker Hub から最新のイメージを直接取得して実行します。

# Pull the latest image
docker pull dog830228/mcp_weather_server:latest

# Run in stdio mode (default)
docker run dog830228/mcp_weather_server:latest

# Run in SSE mode on port 8080
docker run -p 8080:8080 dog830228/mcp_weather_server:latest --mode sse

# Run in streamable-http mode on port 8080
docker run -p 8080:8080 dog830228/mcp_weather_server:latest --mode streamable-http

# Pull a specific version
docker pull dog830228/mcp_weather_server:0.5.0
docker run -p 8080:8080 dog830228/mcp_weather_server:0.5.0 --mode sse

利用可能な Docker イメージ

• 最新：dog830228/mcp_weather_server:latest
• バージョン指定：dog830228/mcp_weather_server:<version>（例：0.5.0）

新しいバージョンのリリース時に、イメージは自動的にビルドされて公開されます。

ソースからのビルド

Docker イメージを自分でビルドする場合：

標準ビルド

# Build
docker build -t mcp-weather-server:sse .

# Run (port will be read from PORT env var, defaults to 8081)
docker run -p 8081:8081 mcp-weather-server:sse

# Run with custom port
docker run -p 8080:8080 mcp-weather-server:local --mode sse

Streamable HTTP ビルド

# Build using streamable-http Dockerfile
docker build -f Dockerfile.streamable-http -t mcp-weather-server:streamable-http .

# Run in stateful mode
docker run -p 8080:8080 mcp-weather-server:streamable-http

# Run in stateless mode
docker run -p 8080:8080 -e STATELESS=true mcp-weather-server:streamable-http

開発

プロジェクト構成

mcp_weather_server/
├── src/
│   └── mcp_weather_server/
│       ├── __init__.py
│       ├── __main__.py          # Main MCP server entry point
│       ├── server.py            # Unified server (stdio, SSE, streamable-http)
│       ├── utils.py             # Utility functions
│       └── tools/               # Tool implementations
│           ├── __init__.py
│           ├── toolhandler.py   # Base tool handler
│           ├── tools_weather.py # Weather-related tools
│           ├── tools_time.py    # Time-related tools
│           ├── tools_air_quality.py # Air quality tools
│           ├── weather_service.py   # Weather API service
│           └── air_quality_service.py # Air quality API service
├── tests/
├── Dockerfile                   # Docker configuration for SSE mode
├── Dockerfile.streamable-http   # Docker configuration for streamable-http mode
├── pyproject.toml
├── requirements.txt
└── README.md

開発用の実行

標準 MCP モード（stdio）

# From project root
python -m mcp_weather_server

# Or with PYTHONPATH
export PYTHONPATH="/path/to/mcp_weather_server/src"
python -m mcp_weather_server

SSE サーバーモード

# From project root
python -m mcp_weather_server --mode sse --host 0.0.0.0 --port 8080

# With custom host/port
python -m mcp_weather_server --mode sse --host localhost --port 3000

Streamable HTTP モード

# Stateful mode (default)
python -m mcp_weather_server --mode streamable-http --host 0.0.0.0 --port 8080

# With debug logging
python -m mcp_weather_server --mode streamable-http --debug

新しいツールの追加

新しい天気関連または時刻関連のツールを追加するには：

1. tools/ の適切なファイルに、新しいツールハンドラーを作成します
2. ToolHandler 基底クラスを継承します
3. 必須メソッド（get_name、get_description、call）を実装します
4. server.py にツールを登録します

依存関係

コア依存関係

• mcp>=1.0.0 - Model Context Protocol の実装
• httpx>=0.28.1 - API リクエスト用 HTTP クライアント
• python-dateutil>=2.8.2 - 日付／時刻の解析ユーティリティ

SSE サーバーの依存関係

• starlette - ASGI Web フレームワーク
• uvicorn - ASGI サーバー

開発用依存関係

• pytest - テスト用フレームワーク

API データソース

このサーバーは、無料のオープンソース API を使用しています：

天気データ：Open-Meteo Weather API

• 無料かつオープンソースです
• API キーは不要です
• 正確な天気予報を提供します
• 世界各地に対応しています
• 過去および現在の天気データを提供します
• 包括的な指標を提供します（風、降水量、UV、視程）

大気質データ：

• 無料かつオープンソースです
• API キーは不要です
• リアルタイムの大気質データを提供します
• 複数の汚染物質を測定します（PM2.5、PM10、O3、NO2、CO、SO2）
• 世界各地をカバーしています
• 健康に基づく大気質指数を提供します

トラブルシューティング

よくある問題

1. 都市が見つからない

• 都市名が英語で入力されていることを確認してください
• 都市名の正式名称を使用するか、国名を含めてください（例：「Paris, France」）
• 都市名のスペルを確認してください

2. HTTP サーバーにアクセスできない（SSE または Streamable HTTP）

• サーバーが正しいモードで実行されていることを確認してください：
  • SSE：python -m mcp_weather_server --mode sse
  • Streamable HTTP：python -m mcp_weather_server --mode streamable-http
• 指定したポートのファイアウォール設定を確認してください
• すべての依存関係がインストールされていることを確認してください：pip install starlette uvicorn
• 正しいエンドポイントを確認してください：
  • SSE：http://localhost:8080/sse および http://localhost:8080/messages/
  • Streamable HTTP：http://localhost:8080/mcp

3. MCP クライアントの接続に関する問題

• MCP クライアントの設定で Python のパスを確認してください
• mcp_weather_server パッケージがインストールされていることを確認してください
• Python 環境に必要な依存関係があることを確認してください

4. 日付形式のエラー

• 日付には ISO 8601 形式を使用してください：YYYY-MM-DD
• start_date が end_date より前であることを確認してください
• 日付が遠い未来になっていないことを確認してください

エラーレスポンス

サーバーは構造化されたエラーメッセージを返します：

{
  "error": "Could not retrieve coordinates for InvalidCity."
}