⚠️ 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-statistics-mcp

Provides the Korea Environment Corporation's AirKorea Air Pollution Statistics Service (ArpltnStatsSvc) OpenAPI as an MCP (Model Context Protocol) server usable by Claude. You can query real-time average information by province/city-county-district and daily/monthly average statistics by monitoring station.

This is the final stage of the AirKorea 3-stage separate development, and is intended to be used together with stage 1 (airkorea-realtime-mcp) and stage 2 (airkorea-forecast-alert-mcp).

Provided Features

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

Related MCP server: seoul-timeavg-air-mcp

About the Scope of This MCP (Important)

Only 4 operations belonging to the Air Pollution Statistics Service (ArpltnStatsSvc) are included. The following 2 operations were originally candidates for stage 3, 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 process):

• getTMStdrCrdnt (TM reference coordinate query) — belongs to the monitoring station information query service (MsrstnInfoInqireSvc), same service group as stage 1 (airkorea-realtime-mcp)

• getUnityAirEnvrnIdexSnstiveAboveMsrstnList (list of monitoring stations with integrated air environment index of "poor" or above) — belongs to the air pollution information query service (ArpltnInforInqireSvc), same service group as stages 1 and 2

Whether to add the two operations to the stage 1 and 2 repositories will be discussed separately (pending status).

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 separately apply for usage of the Air Pollution Statistics Service (ArpltnStatsSvc) on the Public Data Portal (individual usage application required per service ID). It takes 1~2 hours for the application to take effect.

Deployment (fly.io)

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

Connector connection address after deployment:

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

Rate Limit

Since this is a public server accessible without authentication, a 3-tier rate limit based on IP is applied:

• 429 if exceeded 3 times per minute

• 24-hour block if violated 5 times within 1 hour

• 429 if total exceeds 30 times per day (rolling 24h)

When deployed across multiple machines, in-memory counters are separated per machine, so the effective limit may be relaxed in proportion to the number of machines.

Known Limitations (verified by actual measurement, 2026-08-23)

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

• Confirmed that the khaiValue field is actually included in the getCtprvnMesureSidoLIst response.

• Passing sidoName=광주 or 전남 alone returns totalCount=0 (no data) — these two regions must be queried with the merged value 전남광주 to get normal data (actual behavior differs from the specification).

• Error responses are returned normally as JSON within the measured range (codes 30, 10). An XML fallback parser is implemented, but actual XML error responses could not be reproduced — if an XML case is found in the future, it will be additionally recorded in DEVLOG.md.

• SERVICETIMEOUT (504) was not reproduced in local testing — retry logic (up to 3 times) is implemented, but behavior under actual timeout conditions is unverified.

Data Source

• Provider: Korea Environment Corporation (entrusted agency of the Ministry of Environment)

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

• API name: Korea Environment Corporation_AirKorea_Air Pollution Statistics Status (ArpltnStatsSvc)

• License: KOGL Type 1 (Attribution-No Derivatives)

License

MIT License (for the code itself). The original data follows the aforementioned KOGL license.