seoul-timeavg-air-mcp
서울시 기간별 시간평균 대기환경 정보를 조회하는 MCP(Model Context Protocol) 서버입니다.미세먼지, 초미세먼지, 오존, 이산화질소, 일산화탄소, 아황산가스의 시간평균 데이터를측정소/권역 단위로 제공합니다.
데이터 출처
- 제공기관: 서울특별시 기후환경본부 대기정책과
- 플랫폼: 서울 열린데이터광장 — 서비스ID: OA-221,서비스명: 서울시 기간별 시간평균 대기환경 정보 (TimeAverageCityAir)
- 이용허락범위: 공공누리 1유형 (출처표시, 상업적 이용 및 변경 가능)
제공 도구 (Tools)
get_time_average_air
지정한 측정일시(YYYYMMDDHHmm)의 시간평균 대기환경 정보를 조회합니다.
msrmt_dt(필수): 측정일시, YYYYMMDDHHmm 12자리 형식이며 분(mm)은 항상00(예:202401011200). 실측 결과 10자리(YYYYMMDDHH)로는 조회되지 않음.start_index(선택, 기본 1): 조회 시작 위치end_index(선택, 기본 25): 조회 종료 위치 (한 번에 최대 1000건)sarea_nm(선택): 권역명 (예: 도심권, 서북권)msrstn_nm(선택): 측정소명 (예: 종로구, 용산구)
반환 필드: 측정일시, 권역코드/명, 측정소코드/명, 미세먼지 1시간(㎍/㎥), 미세먼지 24시간(㎍/㎥),초미세먼지(㎍/㎥), 오존(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
환경변수
| 변수명 | 설명 |
|---|---|
SEOUL_API_KEY |
서울 열린데이터광장에서 발급받은 인증키 |
PORT |
서버 포트 (기본 8000) |
배포 (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)은TYPE=json요청에도 XML로 반환됩니다.이 서버는 JSON 우선 파싱 후 실패 시 XML로 폴백합니다. - 이 서버는 API 키 없이 누구나 커넥터로 연결할 수 있어, IP 기반 rate limit(분당 3회, 1시간 내 429 5회 이상 시 24시간 차단, 일일 30회 제한)이 적용되어 있습니다.
라이선스
- 코드: MIT License
- 데이터: 공공누리 1유형 (출처표시, 서울특별시)
