weather-forecast-mcp

Provides the Korea Meteorological Administration's short-term forecast inquiry service (VilageFcstInfoService_2.0) as an MCP (Model Context Protocol) server. All four operations — ultra-short-term observation, ultra-short-term forecast, short-term forecast, and forecast version — can be queried by region name or by grid coordinates (nx, ny).

Dataset Registry

This MCP consists of a single API (four operations) and does not integrate additional datasets.

Provided Tools

Installation and Deployment

pip install -r requirements.txt
cp .env.example .env  # WEATHER_FORECAST_SERVICE_KEY 값 입력
python server.py

fly.io deployment:

fly launch --no-deploy
fly secrets set WEATHER_FORECAST_SERVICE_KEY=발급받은키
flyctl deploy

Environment Variables

Specifying a Region

Enter either area_name (e.g., "서울 중구", "종로구 청운효자동") or nx/ny grid coordinates. When area_name is used, the built-in grid mapping table (3,838 administrative districts) automatically matches in the order of level 3 (eup/myeon/dong) → level 2 (si/gun/gu) → level 1 (si/do).

Rate Limit

Because this is a public server, the following three-tier limit applies:

• More than 3 requests per minute → 429

• 5 violations within 1 hour → 24-hour block

• More than 30 requests per day → 429

The fact that the rate limit counter can be separate per machine in the fly.io multi-machine (2 instances) environment is an accepted, known trade-off (availability first).

Verified During Actual Use

• get_vilage_fcst sets numOfRows to a default of 1000 (confirmed against actual responses with totalCount of 742~944 records; truncation occurs if 10 remains the default).

• dataType=JSON error responses really do come back in JSON format (confirmed that an invalid nx/ny request returns a normal JSON resultCode: "10" response). As a safety net, a regex fallback for XML <resultCode>/<resultMsg> is also implemented.

• If an invalid base_time is specified for get_vilage_fcst (e.g., 03:00), a resultCode: "03" (NO_DATA) error is returned, not an empty response.

• Confirmed via actual measurement that short-term forecasts after +4 days (extended period) return PCP/SNO/WSD as qualitative codes (1 = slight, 2 = moderate, 3 = heavy). The server applies this code table whenever fcstDate is at least +4 days after baseDate and marks the response by setting is_extended_period: true.

• get_fcst_version operates normally when basedatetime is provided in the same YYYYMMDDHHmm format as base_time (verified based on ftype=SHRT).

License

MIT

References

• Original API specification: Korea Meteorological Administration, "Open API Usage Guide for the Short-Term Forecast Inquiry Service (2.0)"

• Grid–latitude/longitude mapping table: Excel material provided by the Korea Meteorological Administration (as of July 2026, 3,838 administrative districts)

• Only the South Korean area is supported (North Korea and overseas regions are not provided).