Project 08 · 건축HUB · MCP Server

국토부 건축HUB,
대장을 떼러 가지 마세요.

건축물대장 코드를 외우고, 법정동코드를 조립하고, 표제부 PDF를 스크롤하던 일을 주소 한 줄로. 표제부·층별 구성·노후건물·철거(석면)·공시지가까지 — 전부 data.go.kr 공식 API 실측값이라 그대로 인용 가능. 데이터가 없으면 추측하지 않고 [NOT_FOUND]로 답한다.

12
MCP Tools
3
정부 API (대장·인허가·주택)
43
문서 서식 (10+17+16)
115
테스트 케이스
URL
한 줄 · BYOK 없음
01Killer Feature · 추측 → 실측

건물 정보를 지어내지 않습니다,
없으면 [NOT_FOUND].

일반 AI에게 "이 건물 건폐율"을 물으면 그럴듯한 숫자를 자신 있게 지어낸다. 그 수치가 안전점검 보고서·재건축 검토·감정평가에 들어가면 사고다. 이 커넥터는 매번 건축HUB 공식 API를 실시간 조회하고, 데이터가 없으면 [NOT_FOUND], API 오류면 [EXTERNAL_API_ERROR]를 앞에 붙인다. 추측이 아니라 대장이다.

● 같은 질문, 다른 응답
"자양동 ○○번지 건폐율·용적률 알려줘"
❌ 일반 AI · 추정 (학습 시점 기억)
해당 건물의 건폐율은 약 59%, 용적률은 200% 내외로 추정됩니다. 제2종 일반주거지역 기준 일반적인 범위입니다. ⚠ 출처 없음 · 대장 미조회 · 추정값을 단언 톤으로 응답
✅ archhub-mcp · 실측
건폐율 49.8% · 용적률 187.3% (제2종일반주거지역). 대지면적 1,204㎡ · 연면적 2,254㎡ · 철근콘크리트조 · 1998년 사용승인. 📋 출처: 건축물대장 표제부 · 건축HUB BldRgstHubService
📋

모든 응답이 공식 대장 실측

건폐율·용적률·구조·용도·사용승인일 전부 data.go.kr 건축HUB 원본. 안전점검·재건축 검토·감정평가 자료에 그대로 인용. 출처(서비스명)가 따라붙는다.

없으면 [NOT_FOUND]

대장에 없는 건물·항목은 광역 평균이나 일반론으로 메우지 않고 "데이터 없음"을 명시. LLM이 빈칸을 상상으로 채우는 사고를 원천 차단.

API 오류도 숨기지 않음

건축HUB 응답 실패는 [EXTERNAL_API_ERROR]로 표면화. 빈 응답을 "0건"으로 둔갑시키지 않아, 조회 실패와 진짜 없음을 구분.

🔑

BYOK 없음 · URL만

공용 인증키를 원격 서버에 탑재. 사용자는 키 발급·환경변수 없이 커넥터 URL 한 줄만 등록하면 끝. 발급·세팅 장벽 제로.

02Building Profile · 표제부 한 장

주소 한 줄이면,
건물 한 채가 카드로.

building_profile은 흩어진 표제부 항목 — 용도지역·주용도·구조·규모·건폐율/용적률을 한 장으로 묶는다. building_floors는 지하부터 옥상까지 층별 용도·면적을 스택으로. 주소는 먼저 find_region이 시군구·법정동 코드로 변환한 뒤 넘어간다.

서울 광진구 자양동 ○○○-○ · 근린생활시설
find_region → 11215 / 10500
용도지역
제2종일반주거
주용도
근린생활시설
구조
철근콘크리트조
사용승인
1998
건폐율
49.8 %
용적률
187.3 %
대지면적
1,204
연면적
2,254
규모
지하1 · 지상5
높이
18.6 m
주차
12
승강기
1
5F
사무소
412 ㎡
4F
사무소
412 ㎡
3F
사무소
412 ㎡
2F
제2종근린생활시설
412 ㎡
1F
제1종근린생활시설 · 주차
388 ㎡
B1
주차장 · 기계실
218 ㎡

예시 수치는 표제부 레이아웃을 설명하기 위한 것 — 실제 호출은 입력 주소의 건축HUB 실측값으로 채워진다. 층별 용도·면적이 다르면 building_floors가 층마다 분리해 보여준다.

03Ward-level Aggregation · 실무 동선

건물 한 채를 넘어,
자치구 전체를 한눈에.

개별 조회를 넘어 자치구 단위 집계까지. 노후건물 선별·철거 이력·정비 대상 검토 — 관공서 건축·안전 부서가 매일 만나는 동선을 도구 3종으로 묶었다.

01
district_stats
자치구 건축물 집계 — 건물 수·주용도 분포·연령(준공연도) 코호트·규모 벤치마크. 용도지역 규칙까지 함께. 정비계획·통계 기초자료에.
정비계획
02
old_buildings
연식 필터로 노후건물 선별 — "이 동네 40년 이상 건물" 한 줄. 안전점검 우선순위·재건축 후보 스크리닝. (검증: 자양동 40년↑ 1,551건 실측)
안전점검
03
demolitions
최근 철거 이력 + 석면 함유 부위(천장·단열재·지붕) 플래그. 철거 안전관리·석면 조사 대상 파악에 곧바로.
철거·석면
🏚

노후건물 연식 스크리닝

준공연도 기준 연식 필터. "○○동 30년/40년 이상" 한 줄이면 안전점검·재건축 대상 후보가 리스트로. 광역 평균이 아닌 동 단위 실측.

석면 부위 자동 플래그

demolitions가 철거 건물의 석면 함유 부위를 표기. 철거 전 석면 조사·안전관리 대상을 사전에 식별.

📊

용도·연령·규모 분포

자치구 건축물의 주용도 분포, 준공연도 코호트, 규모 벤치마크를 한 번에. 정비계획·도시계획 기초통계로 바로.

📍

find_region 선행 라우팅

"광진구 자양동"을 시군구코드/법정동코드로 변환해 다른 도구에 넘긴다. 같은 이름 동(○○동)도 상위 시군구를 같이 말하면 정확히 구분.

04Permits & Land Price · 시간축

지금 짓는 중인 건물,
그리고 땅값의 궤적.

permits_pipeline은 사용승인 전(진행 중) 인허가를 공정 단계별로 추적한다. price_history는 공시지가를 시계열로 묶고 CAGR(연평균 변화율)까지 계산 — 감정평가·개발 검토의 시간축 근거.

🏗

permits_pipeline — 진행 중 인허가

사용승인 전 인허가를 공정 단계별로. "이 동네 지금 짓는 중인 건물"을 한 줄로 — 주변 개발 동향·민원 대응·교통영향 검토에.

📈

price_history — 공시지가 CAGR

필지별 공시지가 시계열 + 연평균 변화율. 단순 현재값이 아니라 궤적으로 본다. 감정평가·개발 타당성 검토의 정량 근거.

📑

building_data — 원문 서식 직접 조회

v0.4.0에서 raw 3종을 building_data 하나로 통합. kind=ledger(대장 10종) · permit(인허가 17종) · housing(주택 16종) — 총 43개 문서 서식에 직접 접근. 도구 수를 줄여 LLM 도구 선택 혼란과 스키마 토큰을 함께 절감.

🔗

3개 정부 API 한 서버에

건축물대장 BldRgstHubService · 건축인허가 ArchPmsHubService · 주택인허가 HsPmsHubService를 하나의 MCP로 통합. 호출은 직접 REST로 timeout·행수 제어.

0512 MCP Tools

대부분 질문은,
⭐ 3개 도구로 끝.

find_region · building_profile · district_stats가 일상 질의의 대부분. 나머지는 정밀 조회·원문 서식용.

⭐ find_region
주소 → 시군구·법정동 코드 변환
⭐ building_profile
건물 한 채 종합 카드 (용도지역·정화조 포함)
⭐ district_stats
자치구 집계 + 규모 벤치마크
building_floors
층별 용도·면적 스택
old_buildings
연식 필터 노후건물 선별
price_history
공시가격 시계열 + CAGR
demolitions
철거멸실 + 석면 부위 플래그
permits_pipeline
진행 중 인허가 공정 단계별
seismic_check 🆕
내진 취약 추정 스캔 (1988→2017 연혁)
parcel_history 🆕
필지 연혁 타임라인 (인허가·철거·가설)
temp_buildings 🆕
가설건축물 존치만료 스캔
building_data
원천 서식 직접 조회 (kind=ledger/permit/housing · 43종)
06Install · Remote-first

설치 1분, 사용 즉시.

Claude.ai 웹 커넥터(설치·키 없음) · Claude Code 한 줄 · 데스크톱 앱(mcp-remote) · 로컬 실행(오프라인). 원격은 공용키 탑재라 API 키 발급조차 필요 없다.

🌐 가장 쉬움
Claude.ai 웹 커넥터

Claude Pro/Max/Team — 설정 → 커넥터 → 커스텀 커넥터 추가. URL 한 줄, 키 없음.

https://mcp.gomdori.app/archhub
⌨ Claude Code
한 줄 등록

터미널에서 streamable-http 트랜스포트로 바로 추가.

claude mcp add --transport http \
  archhub https://mcp.gomdori.app/archhub
🖥 데스크톱
Claude · Cursor · Windsurf

mcp-remote 어댑터로 원격 서버 연결. 다른 MCP 서버는 그대로.

{
  "mcpServers": {
    "archhub": {
      "command": "npx",
      "args": ["-y", "mcp-remote",
        "https://mcp.gomdori.app/archhub"]
    }
  }
}
💻 로컬
오프라인 · 직접 실행

data.go.kr 인증키(무료)와 Python 3.10+. 키는 환경변수로.

git clone https://github.com/chrisryugj/archhub-mcp
export ARCHHUB_SERVICE_KEY="<decoded-key>"
archhub-mcp --transport http --port 8000
📚 문서
README · 12 도구 레퍼런스

12개 도구 레퍼런스, 3개 정부 API 매핑, 배포(Fly.io) 가이드, 115 테스트.

README 전체
🔑 data.go.kr 키
로컬 실행 시만 · 무료

공공데이터포털 건축HUB 3개 서비스 신청(일반 인증키 Decoding). 원격 커넥터는 불필요.

data.go.kr
🩺 상태
엔드포인트 헬스

원격 서버 상태 + 일일 호출 수·한도. 클라우드 호스팅(Fly.io) · 12개 도구 동작.

/health