seoul-realtime-air-by-region-mcp

MCP-сервер для получения информации о состоянии атмосферного воздуха в реальном времени по районам Сеула (центральный/северо-восточный/юго-восточный/северо-западный/юго-западный). Основан на API RealtimeCityAir от Seoul Open Data Plaza.

• Организация/отдел: Департамент политики в области качества воздуха Климатического и экологического управления города Сеул

• Исходные данные: Seoul Open Data Plaza — Состояние атмосферного воздуха в реальном времени по районам Сеула

• Лицензия (данные): KOGL Type 1 (указание источника, разрешено коммерческое использование и изменение)

• Лицензия (код): MIT

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

get_realtime_air_by_region

Получает информацию о состоянии атмосферного воздуха в реальном времени по районам (или конкретному району/станции).

Возвращаемые поля: Дата и время измерения (MSRMT_DT), Район (SAREA_NM), Станция (MSRSTN_NM), Мелкие частицы (PM, мкг/м³), Сверхмелкие частицы (FPM, мкг/м³), Озон (OZON, ppm), Диоксид азота (NTDX, ppm), Угарный газ (CBMX, ppm), Диоксид серы (SPDX, ppm), Комплексный класс качества воздуха (CAI_GRD), Комплексный индекс качества воздуха (CAI_IDX), Вещество, определяющее индекс (CRST_SBSTN)

list_available_regions

Возвращает фиксированный список из 5 доступных названий районов (центральный/северо-восточный/юго-восточный/северо-западный/юго-западный). Без вызова API.

Related MCP server: mcp-waqi

Ограничения, подтверждённые на практике

• Ключ аутентификации передаётся как сегмент пути URL (/{KEY}/json/RealtimeCityAir/...), а не как параметр запроса.

• msrstn_nm нельзя использовать отдельно без sarea_nm. Из-за структуры пути API необязательные параметры фиксированы в порядке: место SAREA_NM → место MSRSTN_NM. Если опустить sarea_nm и передать только msrstn_nm, это значение будет интерпретировано как SAREA_NM, и будет возвращён INFO-200 (нет данных). Этот сервер отфильтровывает запросы, содержащие только msrstn_nm, до вызова API и выдаёт понятную ошибку.

• Если расширить диапазон start_index/end_index, фактически возвращается несколько записей (при полном запросе подтверждено 25 записей).

• Нормальные ответы — JSON, но некоторые ответы об ошибках (например, INFO-100 — неверный ключ) возвращаются в XML, даже если запрос был с TYPE=json. Этот сервер использует резервный парсер, который извлекает XML <CODE>/<MESSAGE> при неудаче парсинга JSON.

• Значения CAI_GRD (комплексный класс качества воздуха) на момент измерений были «хорошо» и «нормально» («плохо»/«очень плохо» не наблюдались, но по спецификации возможны).

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

git clone https://github.com/hlucent/seoul-realtime-air-by-region-mcp.git
cd seoul-realtime-air-by-region-mcp
pip install -r requirements.txt
cp .env.example .env  # SEOUL_API_KEY 값 입력
python server.py

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

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

fly launch --no-deploy
fly secrets set SEOUL_API_KEY=<발급받은키>
flyctl deploy

После развёртывания при подключении коннектора Claude.ai регистрируйте с добавлением пути /mcp в следующем виде:

https://<앱이름>.fly.dev/mcp

Безопасность

Сервер открыт без ключа аутентификации, применяется трёхуровневое ограничение частоты запросов на основе IP (3 запроса в минуту — при развёртывании на нескольких машинах может быть смягчено пропорционально количеству машин, при 5 нарушениях в час — блокировка на 24 часа, суточный лимит — 30 запросов).

IP определяется в первую очередь по заголовку Fly-Client-IP (устанавливается непосредственно edge-сервером fly.io, подделка клиентом невозможна). Счётчики ограничения частоты хранятся в памяти (dict) для каждого процесса и не разделяются между машинами, поэтому при распределении запросов fly.io между несколькими машинами фактическое ограничение для одного IP может быть смягчено до «3 запросов в минуту × количество работающих машин». Это компромисс в архитектуре, выбранный для реализации in-memory без внешнего хранилища.

Лицензия

Лицензия MIT. Исходные данные распространяются по лицензии KOGL Type 1.