airkorea-realtime-mcp

This is an MCP server that queries real-time air pollution information, the Comprehensive Air-quality Index (CAI), and measurement station information from the Korea Environment Corporation's AirKorea OpenAPI.

Provided Tools (5)

Related MCP server: mcp-waqi

Data Source

• Providing Organization: Air Quality Policy Support Division, Air Environment Bureau, Climate and Air Quality Office, Korea Environment Corporation

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

• Service Group: Korea Environment Corporation_AirKorea_Air Pollution Information, Korea Environment Corporation_AirKorea_Measurement Station Information, Korea Environment Corporation_AirKorea_Comprehensive Air-quality Index (CAI) query service (Service group code B552584)

• Terms of Use: Attribution-NoDerivatives (Obligation to indicate the data source (Ministry of Environment/Korea Environment Corporation) must be observed)

Measurement Units and Grade Criteria

Grade values: 1=Good, 2=Moderate, 3=Unhealthy, 4=Very Unhealthy

Known Limitations (Verified Through Actual Testing)

• Measurement station list (search_stations) coordinate axes: When called with ver=1.1 fixed, dmX=longitude and dmY=latitude were confirmed to be correct (cross-validated with 5 different stations). Based on WGS84.

• Nearby station query (get_nearby_stations) coordinate system: It was confirmed through actual testing that entering WGS84 latitude/longitude directly produces completely incorrect results (e.g., entering Gangnam-gu, Seoul coordinates returns Jeju Island stations). TM Central Belt (EPSG:5181) coordinate conversion is absolutely required, and this server uses pyproj to automatically convert WGS84→EPSG:5181 before calling the API (users only need to enter latitude/longitude). When entering Gangnam-gu Office coordinates (37.515336, 127.049357), the Gangnam-gu station was returned at the top with a distance of 0.4km, verifying conversion accuracy.

• CAI query (get_station_cai) response fields: Unlike the specification table (khaiValue/khaiGrade/khaiItem), the actual field names are caiValue/caiGrade/caiItem. The full fields are stationCode, stationName, mangName, dataTime, caiValue, caiGrade, caiItem (individual pollutant fields such as so2Value are not included in this operation's response).

• Normal resultCode for CAI query: The other 4 operations return resultCode="00" on success, but only getMsrstnKhaiRltmDnsty (CAI) returns resultCode="200" and resultMsg="NORMAL_CODE" on success. The server code is designed to also treat cases where resultMsg is "NORMAL_CODE"/"NORMAL SERVICE" as successful.

• items response structure difference: ArpltnInforInqireSvc/MsrstnInfoInqireSvc have items as an array, while RltmKhaiInfoSvc (CAI) wraps it one level deeper with items.item. The server absorbs this difference and always returns an array.

• Missing value representation: In this round of actual testing (normal air quality data), the "-" missing case did not appear, but based on the specification examples, _safe_numeric is implemented to safely convert "-"/None/empty strings/floats all to None (it does not arbitrarily replace them with 0).

• API server stability: It was confirmed that SERVICETIMEOUT_ERROR (error code 05, HTTP 504) occurs frequently during actual testing. The server automatically retries up to 3 times only for code 05.

• sidoName "전남광주": Queries work normally (reflecting the launch of Jeonnam-Gwangju Metropolitan City in 2026, totalCount of 64 confirmed).

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

After deployment is complete, connect by appending /mcp to the address.

https://airkorea-realtime-mcp.fly.dev/mcp

Rate Limit Policy

Since this is a public server that can be connected with just a URL without an API key, a 3-tier rate limit based on IP is applied.

• Returns 429 if exceeded 3 times per minute (may be effectively relaxed in proportion to the number of machines in multi-machine deployments)

• If 429 is received 5 or more times within 1 hour, the IP is blocked for 24 hours

• Returns 429 if the daily total (rolling 24 hours) exceeds 30 requests

Error Codes

This API uses the Public Data Portal standard error code system (different from Seoul Open Data Plaza's INFO-000/ERROR-3xx system).

Related Projects

The AirKorea OpenAPI is large in scale, so it is being developed as 3 separate independent MCPs:

License

MIT (code) / KOGL Type 1 (Attribution) — Data source (Ministry of Environment/Korea Environment Corporation) must be indicated