서울시 대기환경 정보 MCP (seoul-air-quality-mcp)

서울특별시 기후환경본부 대기정책과에서 관리하는 대기환경 공공데이터를 AI(Claude 등)가 직접 조회할 수 있도록 만든 MCP(Model Context Protocol) 서버입니다.

담당: 대기정책과 차량공해저감팀 청정 (사무관) 목적: 시민이 "오늘 우리 동네 미세먼지 어때?" 같은 질문을 AI에게 바로 물어보고, 정확한 서울시 공식 데이터로 답을 받을 수 있게 하는 것.

왜 만들었나

광진구청 류승인 주무관님이 korean-law-mcp, kordoc 등을 만들면서 개발 과정을 GitHub에 상세히 기록해두신 것을 보고, "나도 우리 부서 데이터로 이런 걸 만들 수 있지 않을까" 하는 생각에서 시작했습니다.

같은 이유로, 이 저장소도 완성된 코드만 올리는 게 아니라 왜 이렇게 만들었는지, 어떤 시행착오가 있었는지를 함께 남깁니다. 다른 직원분이 비슷한 걸 만들고 싶을 때 이 저장소를 그대로 참고하실 수 있도록 하는 게 목표입니다.

Related MCP server: environment-mcp

사용한 원본 데이터 (서울 열린데이터광장)

원본시스템: 기후대기환경정보서비스 제공부서: 기후환경본부 대기정책과 (☎ 02-2133-3665) 라이선스: 공공누리 1유형 (출처표시 시 상업적 이용·변경 가능)

개발 일지

1단계 — 데이터 파악 (2026-08-01)

서울 열린데이터광장에서 대기정책과 소관 데이터셋을 확인. OA-2275(시간평균 대기오염도)를 1차 대상으로 선정. 연관데이터 탭에서 같은 계열 데이터셋 8~9개를 추가로 확인 → 추후 확장 대상으로 기록.

2단계 — API 인증키 발급

data.seoul.go.kr 회원가입 → 마이페이지에서 인증키 발급 (무료, 일일 호출 제한 있음). 주의: 인증키는 절대 코드에 하드코딩하지 않고 환경변수(SEOUL_API_KEY)로만 사용.

3단계 — API URL 패턴 확인

서울시 열린데이터광장 공통 패턴:

http://openapi.seoul.go.kr:8088/{인증키}/{요청타입}/{서비스명}/{시작인덱스}/{종료인덱스}/

• 확인된 서비스명: RealtimeCityAir (OA-1200, 실시간 자치구별 대기환경)

• TODO: OA-2275(시간평균)의 정확한 서비스명은 로그인 후 Open API 탭에서 확인 필요. 확인되는 대로 main.py의 TODO_SERVICE_NAME 부분을 실제 값으로 교체할 것.

4단계 — MCP 서버 설계

기존에 만들어둔 부동산원+빈집 MCP(FastMCP + Fly.io)와 동일한 구조 채택:

• main.py: FastMCP 서버, SSE transport

• 도구 1개당 API 엔드포인트 1개 매핑이 기본 원칙 (한 도구가 너무 많은 일을 하지 않게)

5단계 — 확장 전략 확정 (2026-08-01)

13개 데이터셋을 한 번에 개발하지 않기로 결정. 이유:

1. 갱신이 오래전에 멈춘 데이터까지 전수 조사 없이 다 넣으면 신뢰도가 오히려 떨어짐.

2. 한 번에 여러 개를 만들면 중간에 지칠 위험이 큼 — 도구 1개씩 완성하고 실제 동작을 확인한 뒤 다음으로 넘어가는 방식 채택. 아래 "MCP 도구 목록 및 확장 로드맵" 표를 기준으로 순서대로 진행.

6단계 — OA-2275 서비스명 확인 및 도구 완성 (2026-08-01)

data.seoul.go.kr 로그인 후 OA-2275의 Open API 탭에서 샘플 URL 확인.

• 서비스명: TimeAverageAirQuality

• URL 패턴: .../{인증키}/{타입}/TimeAverageAirQuality/{시작}/{끝}/{YYYYMMDD 또는 YYYYMMDDHH}/{자치구명(선택)}

• 응답 필드: MSRMT_DT(측정일시), MSRSTN_NM(자치구명), NTDX(NO2), OZON(O3), CBMX(CO), SPDX(SO2), PM(PM10), FPM(PM2.5) get_hourly_air_quality 도구 완성.

7단계 — 배포 (예정)

Fly.io Tokyo 리전으로 배포 예정. 배포 전 Fly.io 지출 한도(월 $5 권장)를 반드시 설정할 것 (이전 작업에서 미설정 상태로 남아있었음 — 이번 프로젝트 배포 전 재확인 필요).

MCP 도구 목록 및 확장 로드맵

원칙: FILE 형태로만 제공되거나 2024년 이전에 갱신이 멈춘 데이터는 실시간 조회에 적합하지 않으므로 제외한다. 대상: 2025~2026년까지 갱신되고 OpenAPI가 제공되는, 대기정책과 소관 데이터만 선정한다. 진행 방식: 도구를 한 번에 다 만들지 않고, 하나씩 추가 → 실제 호출 테스트 → 커밋 → 다음 도구. 매 단계가 하나의 "완주"가 되도록 한다.

이번 단계에서 제외한 데이터

• 서울시 광진구 시간별 대기먼지데이터 (2011~2014, FILE만 제공)

• 서울시 TMS부착사업장 시간단위 대기오염물질 배출농도 (2024-04, FILE만 제공)

• 서울시 대기오염물질 일별 배출량 2019~2021 (FILE만 제공)

• 서울시 대기오염 측정소/측정항목 정보 (보건환경연구원 소관, 대기정책과 아님)

• 서울시 마포구 중앙도서관 공기질(IoT) 측정정보 (정보통신과 소관, 대기정책과 아님)

실행 방법 (로컬 테스트)

python -m venv venv
source venv/bin/activate   # Windows는 venv\Scripts\activate
pip install -r requirements.txt

export SEOUL_API_KEY="발급받은_인증키"
python main.py

배포 (Fly.io)

fly launch --no-deploy
fly secrets set SEOUL_API_KEY="발급받은_인증키"
fly deploy

라이선스 및 출처

원본 데이터: 서울특별시 (공공누리 1유형, 출처표시) 데이터 제공: 서울 열린데이터광장 (data.seoul.go.kr)