airkorea-forecast-alert-mcp

An MCP server that queries the air quality forecast, fine particulate matter alert, and ozone/yellow dust advisory series from the Korea Environment Corporation's AirKorea OpenAPI.

Provided Tools

Design note: Section 3 of DEVPLAN.md first suggested merging the ozone and yellow dust advisories into a single tool (branched by the advisory_type parameter). However, live testing showed that the two operations' response fields differ greatly (ozone returns 8 fields such as concentration values and alert levels, while yellow dust returns only 2 text fields: episode number and region), so bundling them would hurt usability. We therefore split them into 2 separate tools (6 tools total).

Related MCP server: korean-public-data-mcp

Data Source

• Provider: Air Policy Support Division, Atmospheric Environment Agency, Climate and Air Quality Headquarters, Korea Environment Agency

• Platform: Public Data Portal (data.go.kr)

• Service group: Korea Environment Agency_AirKorea_Air Pollution Information (partial), Korea Environment Agency_AirKorea_High-Concentration Ultrafine Particulate Matter (above 50) Forecast Information, Korea Environment Agency_AirKorea_Fine Particulate Matter Numerous Alert Issuance Status, Korea Environment Agency_AirKorea_Ozone/Yellow Dust Occurrence Information (service group code B552584)

• Usage license: Attribution-NoDerivatives — must comply with compulsory source attribution (Ministry of Environment / Korea Environment Agency)

Announcement Schedule (Important)

Known Constraints (Verified via Live Testing, Per Operation — tested on 2026-08-22/23)

get_air_quality_forecast (getMinuDustFrcstDspth)

• informData confirmed to exist in practice. Each item in the items array distinguishes a Today/Tomorrow/Day-after forecast, and the informData value (YYYY-MM-DD) indicates the target date of that forecast. (For example, when dataTime is "2026-08-22 23시 발표", the items arrive in the order of informData "2026-08-22" / "2026-08-23" / "2026-08-24".)

• When querying outside the ozone (O3) season (Nov–Mar), the API returns an empty list without any error (resultCode: "00", totalCount: 0) — verified on 2026-01-15.

• The ver=1.1 parameter was not used in this live test (the default/legacy method is enough and works). Image URLs (imageUrl1 ~ imageUrl9) are returned unchanged for reference.

get_high_pm25_forecast (getMinuDustFrcstDspth50Over)

• The specification sheet has no table of parameters (only references the Swagger document), so everything was confirmed empirically.

• searchDate and the informCode (PM10/PM25/O3) parameter confirmed to work normally.

• All 19 region {region}50Over field names (verified empirically, alphabetically): busan50Over, chungsunbuk50Over, chungnam50Over, daegu50Over, daejeon50Over, gwangju50Over, gyeongbuk50Over, gyeonggibuk50Over, gyeongginam50Over, gyeongnam50Over, incheon50Over, jeju50Over, jeonbuk50Over, jeonnam50Over, sejong50Over, seoul50Over, ulsan50Over, youngdong50Over, youngseo50Over. Note: the {region}Grade fields of the same naming pattern are also provided, returned as "Good / Moderate / Bad / Very bad" text.

• ⚠️ Needs further verification (unresolved): We confirmed the non-exceedance value is "X", but the exceedance value (the spec text's assumed value "O") was not reproduced during the entire month of August 2026 (a seasonally low-PM2.5 period), so it remains unverified. In the code, the spec-assumed value ("O") is kept as the default; re-validation is needed when actual high-concentration events occur.

• The queryable period is limited to approximately the latest month (verified by live testing — using earlier searchDate values returns an empty list with totalCount: 0).

get_pm_alarm_status (getUlfptcaAlarmInfo)

• For alerts that have not been cleared yet, the spec states that offdDate returns "--", clearTime returns ":00", and clearVal returns "공람" (not numeric). This tool converts those fields to null during safe type conversion, and separately provides cleared (bool) / status (string) fields to explicitly indicate the "not cleared (in progress / in effect)" state.

• ⚠️ Needs further verification (unresolved): We queried all actual data from 2025–2026 (a total of 448 records), but every one was already fully cleared; we could not find a case where the un-cleared pattern ("--" / "공람") actually occurs. Re-validation is needed when an un-cleared alert is then issued in the future.

get_ozone_advisory / get_yellowdust_advisory

• Ozone advisories are issued seasonally only from April to October each year (off-season simply has no data; the O3 off-season live test of get_air_quality_forecast above separately confirmed the API itself still operates normally).

• Both get_ozone_advisory and get_yellowdust_advisory were confirmed to work with the year parameter during live testing (for 2026 and 2025).

Common: The Public Data Portal API itself is intermittently unstable

• During live testing, calls to getMinuDustFrcstDspth, getMinuDustWeekFrcstDspth, and getMinuDustFrcstDspth50Over intermittently returned SERVICETIMEOUT_ERROR (code 05) or a pure network timeout. Retrying the same request usually yielded a normal response — this is not a code defect but appears to be load-related instability on the Public Data Portal servers. The client uses an httpx 30-second timeout, and retries by the caller are recommended when needed.

Environment Variables

Installation and Execution (local)

pip install -r requirements.txt --break-system-packages
cp .env.example .env   # AIRKOREA_SERVICE_KEY 값 입력
python server.py

Deployment (fly.io)

fly launch --no-deploy
# fly.toml이 [http_service] 방식인지 확인 후
fly secrets set AIRKOREA_SERVICE_KEY=발급받은키
flyctl deploy

Claude.ai Connector Connection

https://airkorea-forecast-alert-mcp.fly.dev/mcp

Rate Limit Policy

• More than 3 requests per minute → 429 (may be effectively relaxed/boosted in proportion to the number of machines when deploying multiple machines)

• More than 5 datetime occurrences/serving 429 within 1 hour → 24-hour block

• More than 30 total requests per day (rolling 24-hour window) → 429

Error Codes

Uses the public data portal's standard error-code scheme (same as Stage 1 airkorea-realtime-mcp).

Related Projects

Because the AirKorea OpenAPI is large, it is developed as 3 independent MCP server clones:

License

MIT (for code) / complies with Korea Open Government License Type 1 (Attribution) — must state the data source (Ministry of Environment / Korea Environment Corporation).