⚠️ Уведомление о прекращении обслуживания Развёртывание этого MCP-сервера на fly.io прекращено с 2026-08-23. Код оставлен в репозитории для справочных целей при разработке.

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 = ㎍/㎥

Related MCP server: seoul-timeavg-air-mcp

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

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

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

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

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

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

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

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

Внимание: для вызова этого MCP необходимо отдельно подать заявку на использование сервиса статистики загрязнения воздуха (ArpltnStatsSvc) на портале открытых данных (требуется отдельная заявка на использование для каждого идентификатора сервиса). После подачи заявки до фактического отражения проходит 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 нарушениях в течение 1 часа — блокировка на 24 часа

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

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

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

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

• Подтверждено, что поле khaiValue фактически включено в ответ getCtprvnMesureSidoLIst.

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

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

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

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

• Предоставляющая организация: Корейская экологическая корпорация (организация, выполняющая поручение Министерства окружающей среды)

• Платформа: Портал открытых данных (data.go.kr)

• Название API: Корейская экологическая корпорация_ЭйрКорея_Статистика загрязнения воздуха (ArpltnStatsSvc)

• Лицензия: KOGL тип 1 (указание автора — запрет изменений)

Лицензия

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