airkorea-realtime-mcp

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

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

Related MCP server: mcp-waqi

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

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

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

• Группа сервисов: 한국환경공단_에어코리아_대기오염정보, 한국환경공단_에어코리아_측정소정보, 한국환경공단_에어코리아_통합대기환경지수(CAI) 조회 서비스 (код группы сервисов B552584)

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

Единицы измерения и критерии уровня

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

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

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

• Система координат для поиска ближайших станций (get_nearby_stations): на практике подтверждено, что прямая передача координат WGS84 (широты/долготы) даёт совершенно неверные результаты (например, при вводе координат района Каннам в Сеуле возвращаются станции на острове Чеджу). Обязательно требуется преобразование координат в центральную зону TM (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, в ответ этой операции не включаются).

• Код успешного ответа для 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 году, подтверждено totalCount = 64).

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

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

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

Политика Rate Limit

Это публичный сервер, к которому можно подключаться по URL без API-ключа, поэтому применяется трёхуровневое ограничение частоты запросов (rate limit) на основе IP.

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

• Если в течение 1 часа получено 5 или более ответов 429, доступ блокируется на 24 часа

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

Коды ошибок

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

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

Поскольку OpenAPI AirKorea имеет большой объём, он разрабатывается в виде трёх независимых MCP:

Лицензия

MIT (код) / соблюдение лицензии «공공누리» (KOGL) Тип 1 (указание авторства) — с указанием источника данных (Министерство окружающей среды / Корейская экологическая корпорация).