seoul-timeavg-air-mcp

Сервер MCP (Model Context Protocol) для запроса информации о среднем по времени качестве воздуха в Сеуле по периодам. Данные о средних по времени значениях PM10, PM2.5, озона, диоксида азота, угарного газа, диоксида серы предоставляются по станциям/районам.

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

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

• Платформа: Seoul Open Data Plaza — ID сервиса: OA-221, название сервиса: Информация о среднем по времени качестве воздуха в Сеуле по периодам (TimeAverageCityAir)

• Лицензия: Тип 1 Public Nuri (указание источника, коммерческое использование и изменение разрешено)

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

get_time_average_air

Запрашивает данные о среднем по времени качестве воздуха за указанную дату и время (YYYYMMDDHHmm).

• msrmt_dt (обязательно): Дата и время измерения, формат 12 символов YYYYMMDDHHmm, минуты (mm) всегда 00 (например, 202401011200). При 10-значном формате (YYYYMMDDHH) данные не возвращаются.

• start_index (необязательно, по умолчанию 1): Начальная позиция запроса

• end_index (необязательно, по умолчанию 25): Конечная позиция запроса (максимум 1000 записей за раз)

• sarea_nm (необязательно): Название района (например, 도심권, 서북권)

• msrstn_nm (необязательно): Название станции (например, 종로구, 용산구)

Возвращаемые поля: Дата и время измерения, код/название района, код/название станции, PM10 за 1 час (мкг/м³), PM10 за 24 часа (мкг/м³), PM2.5 (мкг/м³), озон (ppm), диоксид азота (ppm), угарный газ (ppm), диоксид серы (ppm)

search_stations

Поиск данных о качестве воздуха на определённый момент по названию станции или района.

• msrmt_dt (обязательно)

• sarea_nm (необязательно)

• msrstn_nm (необязательно)

Установка и локальный запуск

git clone https://github.com/hlucent/seoul-timeavg-air-mcp.git
cd seoul-timeavg-air-mcp
pip install -r requirements.txt
cp .env.example .env
# .env에 SEOUL_API_KEY=발급받은키 입력
python server.py

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

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

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

После развертывания адрес для подключения коннектора Claude.ai:

https://seoul-timeavg-air-mcp.fly.dev/mcp

Известные ограничения

• Ключ аутентификации передается как сегмент пути URL, а не как параметр запроса (http://openAPI.seoul.go.kr:8088/{KEY}/{TYPE}/TimeAverageCityAir/...).

• Максимальное количество записей, которое можно запросить за один раз, составляет 1000 (END_INDEX - START_INDEX ≤ 1000, при превышении возникает ERROR-336). При использовании образцового ключа (sample) максимум составляет 5 записей (ERROR-335).

• MSRMT_DT корректно обрабатывается только в 12-значном формате (YYYYMMDDHHmm, минуты всегда 00). При 10-значном формате возвращается INFO-200 (нет данных).

• Результаты тестирования комбинаций необязательных параметров (название района/название станции):

  • Оба опущены: возвращается всё

  • Указан только sarea_nm: фильтрация по району работает корректно

  • Указан только msrstn_nm (район опущен): обнаружено нестандартное поведение API — фильтр игнорируется и возвращается всё. Данный сервер обнаруживает этот случай и повторно фильтрует ответ по названию станции.

  • Указаны оба: фильтрация работает корректно (пересечение)

• HTTPS не поддерживается (соединение не удается). Используется только HTTP (порт 8088).

• Некоторые ответы об ошибках (например, ERROR-335, ERROR-336) возвращаются в формате XML, даже если запрос был с TYPE=json. Этот сервер сначала пытается разобрать JSON, а при неудаче переключается на XML.

• Поскольку любой может подключиться к этому серверу коннектором без ключа API, применяется IP-базовое ограничение скорости (3 запроса в минуту, при 5+ ошибках 429 в течение часа — блокировка на 24 часа, дневной лимит 30 запросов).

Лицензия

• Код: MIT License

• Данные: Тип 1 Public Nuri (указание источника, город Сеул)