airkorea-statistics-mcp

Предоставляет OpenAPI службы статистики загрязнения воздуха 에어코리아 (ArpltnStatsSvc) от 한국환경공단 в виде MCP(Model Context Protocol) сервера, который может использовать Claude. Можно запрашивать информацию о средних значениях в реальном времени по городам/провинциям и городам/уездам/районам, а также суточную и месячную статистику по измерительным станциям.

Это последний этап трёхэтапной раздельной разработки 에어코리아; предполагается использование вместе с 1 этапом (airkorea-realtime-mcp) и 2 этапом (airkorea-forecast-alert-mcp).

Предоставляемые функции

Единицы измерения: SO2/CO/O3/NO2 = ppm, PM10/PM2.5 = ㎍/㎥

О границах этого MCP (важно)

Включены только четыре операции из службы статистики загрязнения воздуха (ArpltnStatsSvc). Следующие две операции изначально были кандидатами в третий этап, но фактически относятся к другим группам служб и исключены из текущего объёма (основание см. в DEVPLAN.md § 0-1, ход решения — в DEVLOG.md):

• getTMStdrCrdnt (запрос стандартных координат TM) — принадлежит службе запроса информации об измерительных станциях (MsrstnInfoInqireSvc), той же группе служб, что и 1 этап (airkorea-realtime-mcp)

• getUnityAirEnvrnIdexSnstiveAboveMsrstnList (запрос списка измерительных станций, имеющих комплексный индекс качества воздуха «плохо» или выше) — принадлежит службе запроса информации о загрязнении воздуха (ArpltnInfoInqireSvc), той же группе служб, что и 1-й и 2-й этапы

Будет ли добавлены обе операции в репозитории 1-го и 2-го этапов, обсуждается отдельно (статус отложен).

Установка и запуск

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

Переменные окружения

Внимание: Для вызова этого MCP необходимо отдельно подать заявку на использование службы статистикизагрязнения воздуха (ArpltnStatsSvc) на портале 공공데이터포털 (требуется отдельная заявка на использование по каждому ServiceID). После подачи заявки требуется 1–2 часа на фактическое отражение.

Развертывание (fly.io)

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

Адрес подключения коннектора после развёртывания:

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

Rate Limit

Поскольку это публичный сервер, доступный без аутентификации, применяется трёхуровневое ограничение частоты запросов по IP:

• При более чем 3 запросах в минуту — 429

• При 5 и более нарушениях за час — блокировка на 24 часа

• При более чем 30 запросах в сутки (скользящие 24 часа) — 429

При мультимашинном развёртывании внутрипроцессорные счётчики разделяются по машинам, поэтому фактическое ограничение может смягчиться пропорционально количеству машин.

Известные ограничения (подтверждено реальными измерениями, 2026-08-23)

• Числовые поля приходят в виде строк JSON, в коде безопасно преобразуются в float. Отсутствующие значения, как выяснено, могут быть не "-", а пустой строкой ("") (наблюдается в khaiValue, pm10Value, и т. д.).

• Подтверждено, что ответ getCtprvnMesureSidoLIst действительно содержит поле khaiValue.

• При передаче только sidoName=광주 или 전남 возвращается totalCount=0 (нет данных). Для этих двух регионов необходимо передавать объединённое значение 전남광주, чтобы получить корректные данные (фактическое поведение различается со спецификацией).

• Ошибочные ответы в пределах фактически проверенного диапазона (коды 30, 10) возвращаются как JSON. XML fallback-парсер реализован, но реальный XML-ответ с ошибкой не воспроизводится — если в будущем встретится случай с XML, это будет дополнительно отмечено в DEVLOG.md.

• SERVICETIMEOUT(504) не воспроизвёлся в локальных тестах; логика повтора (максимум 3) реализована, но поведение при реальном таймауте не проверено.

Источник данных

• Предоставляющая организация: 한국환경공단 (организация, выполняющая работу по поручению환경부)

• Платформа: 공공데이터포털 (data.go.kr)

• Название API: 한국환경공단_에어코리아_대기오염통계 현황 (ArplStatsSvc)

• Лицензия: 공공누리 제1유형 (указание автора — запрет изменений)

Лицензия

MIT License (код самого). Исходные данные распространяются по вышеуказанной лицензии 공공누ри.