seoul-realtime-air-by-region-mcp

seoul-realtime-air-by-region-mcp

서울시 권역별(도심권/동북권/동남권/서북권/서남권) 실시간 대기환경 현황을 조회하는 MCP 서버입니다.서울 열린데이터광장의 RealtimeCityAir API를 기반으로 합니다.

• 제공기관/부서: 서울특별시 기후환경본부 대기정책과
• 원본 데이터: 서울 열린데이터광장 — 서울시 권역별 실시간 대기환경 현황
• 라이선스(데이터): 공공누리 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 호출 없음.

실측으로 확인된 제약사항

• 인증키는 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) 등 일부 에러 응답은 TYPE=json 요청에도 XML로돌아옵니다. 이 서버는 JSON 파싱 실패 시 XML <CODE>/<MESSAGE>를 추출하는 폴백 파서를 사용합니다.
• 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단계 rate limit이 적용되어 있습니다(분당 3회 — 멀티 머신 배포 시 머신 수에 비례해 실질 완화될 수 있음, 시간당 5회 위반 시24시간 차단, 일 30회 총량 제한).

IP는 Fly-Client-IP 헤더(fly.io 엣지가 직접 설정, 클라이언트 위조 불가)를 우선 사용합니다.rate limit 카운터는 인메모리(dict)로 프로세스별로 유지되며 머신 간 공유되지 않으므로,fly.io가 요청을 여러 머신에 분산하는 경우 동일 IP 기준 실질 제한이 "분당 3회 × 실행 중인머신 수"로 완화될 수 있습니다. 이는 외부 저장소 없이 in-memory로 구현하기로 한 설계상트레이드오프입니다.

라이선스

MIT License. 원본 데이터는 공공누리 1유형을 따릅니다.