⚠️ Service Termination Notice This MCP server ended its fly.io deployment on 2026-08-23. The code remains in the repository for development reference.

airkorea-realtime-mcp

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

Provided Tools (5)

Related MCP server: seoul-air-quality-mcp

Data Source

• Provider: Korea Environment Corporation, Climate & Air Quality Bureau, Air Environment Division, Air Policy Support Department

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

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

• License Scope: Attribution-NoDerivatives (obligation to indicate the data source (Ministry of Environment/Korea Environment Corporation))

Measurement Units and Grade Criteria

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

Known Limitations (verified through actual measurements)

• Station list (search_stations) coordinate axes: When called with ver=1.1 fixed, dmX=longitude, dmY=latitude confirmed normal (cross-validated with 5 different stations). Based on WGS84.

• Nearby station lookup (get_nearby_stations) coordinate system: Entering WGS84 lat/long directly produces completely wrong results (e.g., entering Gangnam-gu, Seoul coordinates returns Jeju Island stations), as verified by actual measurement. TM Central Belt (EPSG:5181) coordinate conversion is mandatory, and this server automatically converts WGS84→EPSG:5181 using pyproj before calling the API (the user only needs to enter lat/long). Entering Gangnam-gu Office coordinates (37.515336, 127.049357) returned the Gangnam-gu station at the top with a distance of 0.4km, validating conversion accuracy.

• CAI lookup (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).

• CAI lookup normal resultCode: The other 4 operations return resultCode="00" on success, but only getMsrstnKhaiRltmDnsty (CAI) responds with resultCode="200", resultMsg="NORMAL_CODE" on success. The server code is designed to also treat resultMsg values of "NORMAL_CODE"/"NORMAL SERVICE" as normal.

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

• Missing value representation: In this measurement range (normal air quality data), no "-" missing cases appeared, but based on the specification examples, _safe_numeric is implemented to safely convert "-"/None/empty strings/floats all to None (not arbitrarily replacing with 0).

• API server stability: SERVICETIMEOUT_ERROR (error code 05, HTTP 504) was frequently observed during measurement. The server automatically retries up to 3 times for code 05 only.

• sidoName "전남광주": Queries successfully (reflecting the 2026 launch of Jeonnam-Gwangju Special City, 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, connect by appending /mcp to the address.

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

Rate Limit Policy

Since this is a public server accessible by URL alone without an API key, a 3-tier IP-based rate limit applies.

• More than 3 requests per minute returns 429 (may be effectively relaxed in proportion to the number of machines in multi-machine deployments)

• Receiving 429 five or more times within an hour results in a 24-hour block

• More than 30 total requests per day (rolling 24 hours) returns 429

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 developed as 3 separate independent MCPs:

License

MIT (code) / KOGL Type 1 (Attribution) compliance — data source (Ministry of Environment/Korea Environment Corporation) attribution required