seoul-uncomfort-report-mcp

서울시 스마트 불편신고 분야별 신고 현황, 서울시 위치별 불편신고건수 정보, 서울시 년도별/월별 불편신고건수 정보를 조회하는 MCP 서버입니다. 서울열린데이터광장(data.seoul.go.kr) 오픈API를 기반으로 합니다.

이 MCP에 통합된 원본 데이터셋 (Dataset Registry)

이 표가 이 MCP의 "구성 목록"입니다. 새 데이터셋을 추가하거나 새 MCP를 만들기 전에 먼저 이 표를 봐서 판단하세요 — 왼쪽 열은 서울열린데이터광장(data.seoul.go.kr) 목록 화면에서 실제로 보이는 이름 그대로이므로, 화면을 열어놓고 눈으로 바로 대조할 수 있습니다. API 코드명(SERVICE)이나 다른 문서를 다시 열어볼 필요 없이 이 표 하나로 판단이 끝나도록 만든 것입니다.

열린데이터광장 화면 표시명 (그대로)	제공부서 (화면 표시 그대로)	이 MCP 포함 여부	서비스명(SERVICE)
서울시 스마트 불편신고 분야별 신고 현황	디지털도시국 공간정보과	✅ 포함됨 (툴 1)	SmartUncomfStatSector
서울시 위치별 불편신고건수 정보	디지털도시국 공간정보과	✅ 포함됨 (툴 2)	SmartUncomfStatLocale
서울시 년도별/월별 불편신고건수 정보	디지털도시국 공간정보과	✅ 포함됨 (툴 3)	SmartUncomfStatMonth

화면 목록 순서(수정일자순)가 바뀌면 표 순서와 안 맞을 수 있으니, 판단 기준은 항상 "데이터셋명" + "제공부서" 두 열의 일치 여부입니다. 순서는 무시해도 됩니다.

새 데이터셋을 봤을 때, 이 표만 보고 3초 안에 판단하는 법

1. 화면에서 데이터셋명이 위 표의 왼쪽 열에 이미 있다 → 아무것도 안 해도 됨 (중복)
2. 화면에서 데이터셋명은 처음 보는데, 제공부서가 "디지털도시국 공간정보과"이고 설명에 "서울시 스마트 불편신고"가 들어간다 → 이 MCP에 툴 추가 검토 대상.
3. 제공부서가 다르다 (예: "보도상영업시설물", "노동조합" 등 다른 부서 제공 데이터셋) → 이 MCP와 무관. 완전히 새 MCP 프로젝트로 진행.

이 판단에 API 호출이나 Claude 재질문이 필요 없도록, 이 표는 화면 캡처 명칭을 그대로 써서 사람이 직접 대조 가능하게 만들었습니다.

제공 툴

1. get_uncomfort_report_by_sector

분야별(교통, 도로, 청소, 주택건축, 치수방재, 가로정비, 보건, 공원녹지, 환경, 경제/산업, 소방안전, 기타 불편사항) 불편신고 건수를 조회합니다. 단위: 건수.

파라미터: year(선택), month(선택), start_index(기본 1), end_index(기본 20)

2. get_uncomfort_report_by_district

서울시 25개 자치구 + 타시도 기준 불편신고 건수를 조회합니다. 단위: 건수.

파라미터: year(선택), month(선택), start_index(기본 1), end_index(기본 20)

3. get_uncomfort_report_by_month

연도별 1~12월 불편신고 건수와 연간 합계를 조회합니다. 단위: 건수. 주의: 이 서비스는 월(MONTH) 파라미터가 없습니다 — 연도 전체 데이터만 조회 가능합니다. 아직 지나지 않은 달은 데이터가 비어 있습니다(예: 조회 시점이 2026년 7월이면 8~12월은 값 없음).

파라미터: year(선택), start_index(기본 1), end_index(기본 20)

설치 및 실행 (로컬)

pip install -r requirements.txt
cp .env.example .env  # SEOUL_API_KEY 입력
python server.py

환경변수

변수명	설명
SEOUL_API_KEY	서울열린데이터광장에서 발급받은 인증키
PORT	서버 포트 (기본 8000)

배포

fly.io 배포 방식은 CLAUDE.md, 프로젝트 공통 지침을 따릅니다. 배포 완료 후 Claude.ai 커넥터 연결 시 URL 끝에 /mcp를 붙여야 합니다. 예: https://seoul-uncomfort-report-mcp.fly.dev/mcp

데이터 출처 및 라이선스

• 제공기관: 서울특별시
• 제공부서: 디지털도시국 공간정보과
• 원본시스템: 서울시 스마트 불편신고
• 이용허락범위: 공공누리 1유형 (출처표시, 상업적 이용 및 변경 가능)

알려진 제약사항 (실측 확인 완료)

• 인증키는 URL 경로 세그먼트 방식(/{KEY}/json/{SERVICE}/...)으로 전달하면 정상 동작합니다. 쿼리 파라미터 방식은 별도로 시도하지 않았습니다(경로 방식이 첫 시도에서 성공).
• 3개 서비스(SmartUncomfStatSector, SmartUncomfStatLocale, SmartUncomfStatMonth) 모두 동일한 SEOUL_API_KEY 하나로 정상 동작함을 실측 확인했습니다.
• YEAR/MONTH 선택 파라미터는 전부 생략, YEAR만 지정, YEAR+MONTH 모두 지정 조합 모두 정상 동작합니다. SmartUncomfStatMonth는 MONTH 파라미터 자체가 없으므로 YEAR 단독으로만 동작합니다(실측 확인).
• API 응답에서 결과가 1건일 때와 여러 건일 때 JSON 구조가 다를 수 있어(단일 dict vs list) 서버 내부에서 항상 리스트로 정규화합니다.
• 숫자 필드는 JSON에서 실수(예: 55567.0)로 옵니다. 아직 지나지 않은 달의 빈 태그(예: MON_08)는 null이 아니라 0.0으로 옵니다. 서버에서 모두 정수로 안전 변환하여 반환합니다.
• 이 서버는 API 키 인증 없이 공개되며, IP 기준 rate limit이 적용됩니다 (분당 3회, 1시간 내 5회 위반 시 24시간 차단, 24시간 총 30회 — 멀티 머신 배포 시 머신 수에 비례해 실질 완화될 수 있음).

라이선스

MIT