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

서울시 대기환경정보 MCP (seoul-air-quality-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 리전으로 배포 완료.

MCP 도구 목록 및 확장 로드맵

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

다음 확장 단계 (보건환경연구원 제공 데이터셋)

대기정책과(기후환경본부) 제공 데이터셋을 모두 연결 완료한 뒤, 제공기관이 다른 아래 데이터셋으로 확장 예정입니다.

• 서울시 대기오염 측정정보 (OA-15526, 서울특별시 보건환경연구원 대기질통합분석센터 제공)
• 서울시 대기오염 측정소 정보 (OA-15516, 좌표 데이터 포함 가능성 있어 함께 검토)

모든 데이터셋 등록이 끝나면, 측정소 좌표를 확보해 도로 구간별 대기질 지도 시각화(공무원 단속·점검 동선 최적화, 시민의 청정 경로 선택 지원)로 확장할 계획입니다.

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

• 서울시 광진구 시간별 대기먼지데이터 (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

출처 표기 설계 원칙

이 MCP는 단순히 데이터를 가져오는 것을 넘어, 모든 응답에 출처가 자동으로 포함되도록 설계했습니다.

• 모든 도구 응답에는 _data_source 필드가 포함되며, 여기에 원본 데이터셋명, OA번호, data.seoul.go.kr 상세페이지 URL이 담깁니다.
• 단순히 필드 설명(description)만 적어두면 실제 응답에서 출처가 누락되는 경우가 있었습니다. 이를 방지하기 위해 도구 docstring에 다음과 같은 명령형 문구를 명시했습니다: "⚠️ 중요: 답변 끝에 출처를 반드시 명시하라"
• 이렇게 설계한 이유는, 공무원이 이 MCP로 조회한 데이터를 보고서에 인용할 때 데이터의 진위와 근거를 항상 확인할 수 있어야 하기 때문입니다.

실시간치와 확정치 구분 원칙

실시간(잠정치) 데이터와 국가가 검증한 확정치 데이터를 도구명·설명(description)·응답 메타데이터 세 층위에서 명확히 구분되도록 설계했습니다. 정책보고서나 공식 통계 인용에는 확정치를, 실시간 대시보드나 즉각 대응에는 잠정치를 사용하도록 혼용을 방지하는 것이 목표입니다.

라이선스 및 출처

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

사용 데이터셋 및 구현 현황

참고: API 키는 데이터셋마다 따로 발급받지 않고, 서울 열린데이터광장에서 발급받은 인증키 하나(SEOUL_API_KEY)로 모든 Open API를 사용합니다.

데이터셋 유지보수 원칙

각 데이터셋은 최근 2년 이내 갱신 이력이 있어야 이 MCP에 포함합니다.

• 데이터셋 페이지의 "데이터갱신일"이 2년 이상 경과하면:
  1. 해당 도구를 코드에서 제거하거나 비활성화
  2. 위 표에서 "폐기 (마지막 갱신: YYYY.MM)"로 표시 후 일정 기간 뒤 표에서도 삭제
  3. 유사한 신규 데이터셋이 있는지 확인하여 대체
• 정기 점검: 매년 초 전체 데이터셋의 갱신일자를 재확인

배포 검증 이력

• 2026-08-02: main.py에서 3번째 도구(get_yearly_pm10_alerts)가 mcp.run() 호출 뒤에 정의되어 있어 서버 실행 시 등록되지 않던 버그를 수정(도구 순서 재배치). Fly.io 재배포 후 Claude Desktop 커넥터에서 도구 3개(get_realtime_air_quality, get_hourly_air_quality, get_yearly_pm10_alerts) 전체 정상 인식 및 실제 호출 테스트 완료. get_yearly_pm10_alerts의 _data_quality_warning 로직도 의도대로 작동하여 원본 데이터셋(OA-2228) 결측 가능성을 정상적으로 안내함.

• 2026-08-02: get_realtime_air_quality, get_hourly_air_quality에 환경부 통합대기환경지수(CAI) 기준 등급(cai_grade)·행동요령(cai_guidance) 자동 계산 로직 추가. 단, get_hourly_air_quality는 시간값을 기준으로 근사 계산하며, 공식 24시간 평균 기준 등급과는 다를 수 있음.

🔌Claude에 연결하는 방법

설치 없이 URL 하나만으로 연결할 수 있습니다. 소요시간 약 3분.

📋 사전 준비 — 서울 열린데이터광장 API 키 발급data.seoul.go.kr 접속 → 회원가입 후 로그인오른쪽 상단 내 정보 → 인증키 관리 클릭발급된 인증키(API Key)를 복사해서 메모장에 저장

✅ 무료입니다. 별도 심사 없이 즉시 발급됩니다.

연결 URL 형식

https://seoul-air-quality-mcp.fly.dev/mcp?key=여기에본인API키붙여넣기

예시:

https://seoul-air-quality-mcp.fly.dev/mcp?key=abc1234567890xyz

방법 1 — Claude.ai 웹/앱에서 연결 (가장 간단)claude.ai 접속 후 로그인왼쪽 하단 프로필 아이콘 → Settings(설정) 클릭왼쪽 메뉴에서 Connectors(커넥터) 선택Add custom connector 버튼 클릭아래와 같이 입력:항목 입력값이름 서울시 대기환경정보 MCP원격 MCP 서버 URL https://seoul-air-quality-mcp.fly.dev/mcp?key=본인API키Save 클릭 → 대화창에서 바로 사용 가능

방법 2 — Claude Desktop 앱에서 연결설정 파일(claude_desktop_config.json)을 열어 아래 내용을 추가합니다.설정 파일 위치 (Windows):

%APPDATA%\Claude\claude_desktop_config.json

추가할 내용:

{
  "mcpServers": {
    "서울시 대기환경정보 MCP": {
      "type": "http",
      "url": "https://seoul-air-quality-mcp.fly.dev/mcp?key=본인API키"
    }
  }
}

💡 파일이 이미 있는 경우, "mcpServers": { } 안에 위 내용을 추가하세요. 저장 후 Claude Desktop을 재시작하면 연결됩니다.

💬 연결 후 이렇게 질문해 보세요

지금 서울 대기질 어때?

오늘 강남구 미세먼지 알려줘

어제 시간대별 서울 오존 농도 보여줘

Made by hlucent