airkorea-statistics-mcp

Provides the Korea Environment Corporation AirKorea Air Pollution Statistics Service (ArpltnStatsSvc) OpenAPI as an MCP (Model Context Protocol) server that Claude can use. You can query real-time averages by city/province (시도), real-time averages by city/county/district (시군구), and daily or monthly average statistics by monitoring station.

This is the final stage in the three-stage separated development of AirKorea, and it is intended to be used together with Stage 1 (airkorea-realtime-mcp) and Stage 2 (airkorea-forecast-alert-mcp).

Features

Measurement units: SO2/CO/O3/NO2 = ppm, PM10/PM2.5 = ㎍/㎥

About the scope of this MCP (Important)

Only the 4 operations belonging to the Air Pollution Statistics Service (AirPtnStatsSvc) are included. The 2 operations below were originally candidates for this stage, but they actually belong to other service groups and were excluded from this scope (see Section 0-1 of DEVPLAN.md for the rationale and DEVLOG.md for the decision history):

• getTMStrdCrdnt (query TM standard coordinates) — belongs to the monitoring station information query service (MsrstnInfoInquirySvc), the same service group as Stage 1 (airkorea-realtime-mcp)

• getUnityAirEnvironmentIndexSensitiveAboveMsrstnList (query list of monitoring stations with an integrated air environment index of "bad" or above) — belongs to the air pollution information query service (ArpltnInforInquirySvc), the same service group as Stages 1 and 2

Whether to add these two operations to the Stage 1 and Stage 2 repositories will be discussed separately (currently pending).

Installation and Execution

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

Environment Variables

Note: To call this MCP, you must have separately applied for the Air Pollution Statistics Service
(ArpltnStatsSvc) on the Public Data Portal (a separate application is required per service ID). After applying, the service is not available until applied to your key. It may take 1~2 hours until the application is reflected.

Distribution (fly.io)

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

After deployment, connector connection address:

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

Rate Limit

The server is publicly accessible without authentication, so an IP-based three-level rate limit applies:

• More than 3 requests per minute returns 429

• 3 violations or more within 1 hour blocks the caller for 24 hours

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

When deploying on multiple machines, in-memory counters are isolated per machine, so the effective limit may be relaxed in proportion to the number of machines.

Known limitations (verified by actual tests, 2026-08-23)

• Numeric fields arrive as JSON strings, and are safely converted to float in code. Missing values are confirmed to be empty strings ("") rather than "-" (observed in khaiValue, pm10Value, etc.).

• The khaiValue field was confirmed to be actually included in responses of getCityAir.ug — we have verified the khaiValue field in the response.

• If sidoName=광주 or 전남 is passed alone, totalCount=0 (no data) is returned — both regions must be queried with the merged value 전남광주 to get valid data (actual behavior differs from the specification).

• Error responses are correctly returned in JSON within the tested range (error codes 30, 10). An XML fallback parser is implemented, but actual XML error responses could not be reproduced — if a case with an XML error is found later, it will be documented in DEVLOG.md.

• SERVICETIMEOUT(504) could not be reproduced in local tests — retry logic (up to 3 times) is implemented, but its behavior in real timeouts is not verified.

Data Sources

• Provider Agency: Korea Environment Corporation (Korean environment ministry trust institution)

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

• API name: 한국환경공단_에어코리아_대기오염통계 현황 (ArpltnStatsSvc)

• License: KOGL Type 1 (Attribution No Derived Works)

License

The code itself is MIT License. The original data follows the abovementioned Public Daten license.