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

airkorea-realtime-mcp

MCP-сервер для запроса информации о качестве воздуха в реальном времени, комплексного индекса качества воздуха (CAI) и информации о станциях мониторинга через OpenAPI Air Korea Корейской корпорации по охране окружающей среды.

Предоставляемые инструменты (5 шт.)

Related MCP server: seoul-air-quality-mcp

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

• Предоставляющая организация: Отдел политики поддержки качества воздуха, Департамент качества воздуха, Управление климата и качества воздуха, Корейская корпорация по охране окружающей среды

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

• Группа сервисов: Korea Environment Corporation_Air Korea_Информация о загрязнении воздуха, Korea Environment Corporation_Air Korea_Информация о станциях мониторинга, Korea Environment Corporation_Air Korea_Сервис запроса комплексного индекса качества воздуха (CAI) (код группы сервисов B552584)

• Область разрешения на использование: Указание авторства-запрет изменений (обязательное соблюдение указания источника данных (Министерство окружающей среды/Корейская корпорация по охране окружающей среды))

Единицы измерения и критерии классов

Значения класса (Grade): 1=хорошо, 2=нормально, 3=плохо, 4=очень плохо

Известные ограничения (подтверждено практическими измерениями)

• Оси координат списка станций (search_stations): при вызове с фиксированным ver=1.1 подтверждено, что dmX=долгота, dmY=широта (перекрёстная проверка выполнена на 5 различных станциях). По стандарту WGS84.

• Система координат запроса ближайших станций (get_nearby_stations): практическими измерениями подтверждено, что при вводе координат WGS84 (широта/долгота) напрямую возвращаются совершенно неверные результаты (например, при вводе координат района Каннамгу в Сеуле возвращаются станции на острове Чеджудо). Обязательно требуется преобразование координат в TM Central Belt (EPSG:5181); данный сервер автоматически преобразует WGS84→EPSG:5181 с помощью pyproj и затем вызывает API (пользователю нужно ввести только широту/долготу). При вводе координат администрации района Каннамгу (37.515336, 127.049357) станция района Каннамгу возвращается первой с расстоянием 0.4 км, что подтверждает точность преобразования.

• Поля ответа запроса CAI (get_station_cai): в отличие от таблицы в спецификации (khaiValue/khaiGrade/khaiItem), фактические имена полей — caiValue/caiGrade/caiItem. Полный набор полей: stationCode, stationName, mangName, dataTime, caiValue, caiGrade, caiItem (поля отдельных загрязняющих веществ, такие как so2Value, в ответ этой операции не включаются).

• Нормальный resultCode запроса CAI: у остальных 4 операций при нормальном выполнении resultCode="00", но только getMsrstnKhaiRltmDnsty(CAI) при нормальном выполнении отвечает resultCode="200", resultMsg="NORMAL_CODE". Код сервера обрабатывает как нормальное выполнение также случаи, когда resultMsg равен "NORMAL_CODE"/"NORMAL SERVICE".

• Различие в структуре ответа items: у ArpltnInforInqireSvc/MsrstnInfoInqireSvc items — массив, а у RltmKhaiInfoSvc(CAI) данные обёрнуты на один уровень глубже — items.item. Сервер поглощает это различие и всегда возвращает массив.

• Представление пропущенных значений: в текущем диапазоне практических измерений (нормальные данные о качестве воздуха) случаи пропусков "-" не встречались, но на основе примеров из спецификации _safe_numeric реализован так, чтобы безопасно преобразовывать "-"/None/пустую строку/число с плавающей точкой (float) в None (без произвольной замены на 0).

• Стабильность API-сервера: в ходе практических измерений подтверждено частое возникновение SERVICETIMEOUT_ERROR (код ошибки 05, HTTP 504). Сервер автоматически повторяет попытку до 3 раз только для кода 05.

• sidoName "전남광주": запрос выполняется нормально (отражает создание особого города Чоннам-Кванджу в 2026 году, подтверждено 64 записи в totalCount).

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

Установка и запуск (локально)

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

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

fly launch --no-deploy
# fly.toml이 [http_service] 방식인지 확인 후
fly secrets set AIRKOREA_SERVICE_KEY=발급받은키
flyctl deploy

Подключение через коннектор Claude.ai

После завершения развёртывания подключитесь, добавив /mcp к адресу.

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

Политика ограничения частоты запросов

Поскольку это открытый сервер, к которому можно подключиться по URL без ключа API, применяется 3-уровневое ограничение частоты запросов по IP.

• Более 3 запросов в минуту — 429 (при многосерверном развёртывании фактическое смягчение может быть пропорционально количеству серверов)

• При получении 429 более 5 раз в течение 1 часа — блокировка на 24 часа

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

Коды ошибок

Этот API использует стандартную систему кодов ошибок портала открытых государственных данных (отличается от системы INFO-000/ERROR-3xx Открытой площадки данных Сеула).

Связанные проекты

API Air Korea имеет большой масштаб, поэтому разрабатывается как 3 независимых MCP:

Лицензия

MIT (код) / соблюдение KOGL Type 1 (указание авторства) — указание источника данных (Министерство окружающей среды/Корейская корпорация по охране окружающей среды)