airkorea-forecast-alert-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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
Tool | Description |
| Retrieve air quality (PM/ozone) forecast bulletins — today/tomorrow/day-after forecasts, forecast overview, causes, and action guidance |
| Retrieve the weekly ultrafine particulate matter (PM2.5) forecast — Low/High forecast for 4 days starting 3 days out |
| Retrieve high-concentration PM2.5 (above 50) forecast data — whether PM2.5 exceeds 50 ㎍/㎥ in each of the 19 regions |
| Retrieve PM alert status — advisory/warning issuance and clearance history by region |
| Retrieve ozone advisory occurrence information |
| Retrieve yellow dust advisory occurrence information |
Design note: Section 3 of DEVPLAN.md first suggested merging the ozone and yellow dust advisories into a single tool (branched by the
advisory_typeparameter). 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: seoul-realtime-air-by-region-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)
Item | Announcement schedule |
Fine Particulate Matter forecast (today/tomorrow/day after) | 4 times daily (05:00 / 11:00 / 17:00 / 23:00), 19 regions |
Ozone forecast | Issued only from April 1 to October 31 each year. Today's forecast at 05:00/11:00 (additional 17:00 release when peculiar conditions occur) |
Weekly PM2.5 forecast | Once daily at 17:30, 19 regions, 4 days starting 3 days out |
High-concentration PM2.5 (above 50) forecast | 4 times daily (05:00 / 11:00 / 17:00 / 23:00), delivered within about 10 minutes for each city |
Known Constraints (Verified via Live Testing, Per Operation — tested on 2026-08-22/23)
get_air_quality_forecast (getMinuDustFrcstDspth)
informDataconfirmed to exist in practice. Each item in the items array distinguishes a Today/Tomorrow/Day-after forecast, and theinformDatavalue (YYYY-MM-DD) indicates the target date of that forecast. (For example, whendataTimeis"2026-08-22 23시 발표", the items arrive in the order ofinformData"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.1parameter 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.
searchDateand theinformCode(PM10/PM25/O3) parameter confirmed to work normally.All 19 region
{region}50Overfield 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}Gradefields 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
searchDatevalues returns an empty list withtotalCount: 0).
get_pm_alarm_status (getUlfptcaAlarmInfo)
For alerts that have not been cleared yet, the spec states that
offdDatereturns"--",clearTimereturns":00", andclearValreturns"공람"(not numeric). This tool converts those fields tonullduring safe type conversion, and separately providescleared(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_forecastabove separately confirmed the API itself still operates normally).Both
get_ozone_advisoryandget_yellowdust_advisorywere confirmed to work with theyearparameter during live testing (for 2026 and 2025).
Common: The Public Data Portal API itself is intermittently unstable
During live testing, calls to
getMinuDustFrcstDspth,getMinuDustWeekFrcstDspth, andgetMinuDustFrcstDspth50Overintermittently returnedSERVICETIMEOUT_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 anhttpx30-second timeout, and retries by the caller are recommended when needed.
Environment Variables
Variable | Description |
| Air Korea service key issued from the Public Data Portal (Decoding key) |
Installation and Execution (local)
pip install -r requirements.txt --break-system-packages
cp .env.example .env # AIRKOREA_SERVICE_KEY 값 입력
python server.pyDeployment (fly.io)
fly launch --no-deploy
# fly.toml이 [http_service] 방식인지 확인 후
fly secrets set AIRKOREA_SERVICE_KEY=발급받은키
flyctl deployClaude.ai Connector Connection
https://airkorea-forecast-alert-mcp.fly.dev/mcpRate 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).
Code | Meaning |
00 | Normal |
03 | No Data |
10 | Invalid request parameter |
11 | Missing required parameter |
20 | Service access denied |
22 | Daily traffic limit exceeded |
30 | Unregistered service key |
31 | Service key validity period expired |
Related Projects
Because the AirKorea OpenAPI is large, it is developed as 3 independent MCP server clones:
Stage | Repository | Scope of scope |
Stage 1 |
| Real-time measurement information, CAI, station information |
Stage 2 (this project) |
| Air quality forecasts, weekly PM2.5 forecasts, high-concentration forecasts, PM alerts, ozone advisories, yellowish dust advisories |
Stage 3 |
| Statistics by province/city and monitoring stations (daily/monthly average), CAI stations rated "Bad" or worse |
License
MIT (for code) / complies with Korea Open Government License Type 1 (Attribution) — must state the data source (Ministry of Environment / Korea Environment Corporation).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Free, keyless real-time air quality (US AQI plus PM2.5, PM10, ozone, NO2, SO2, CO) for any city.
Unofficial Air Quality MCP — wraps air-quality-api.open-meteo.com (free, no auth)
Access UK air quality data, monitoring sites, and hourly pollutant measurements across regions
Seoul Open Data MCP — city data for Seoul via the Seoul Open Data Plaza API (openapi.seoul.go.kr).…
Related MCP Servers
- FlicenseBqualityDmaintenanceConnects to the Korea Meteorological Administration (KMA) Open API to provide short-term and ultra-short-term weather forecasts for South Korea. It enables users to query current weather conditions and future forecasts based on latitude and longitude.2-
- AlicenseNot gradedqualityDmaintenanceEnables querying real-time air quality data by region in Seoul, South Korea, using the Seoul Open Data Platform API, supporting multiple regions and monitoring stations.MIT
- AlicenseNot gradedqualityDmaintenanceEnables querying real-time air quality measurements, integrated air quality index (CAI), and monitoring station information from Korea's Air Korea OpenAPI, including station search and nearby station lookup.MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude to query AirKorea's air pollution statistics, including real-time averages by province and city/county, as well as daily and monthly averages by monitoring station.MIT