부동산·건축 실측 데이터를 말 한마디로! 건축HUB MCP 활용 가이드

부동산·건축 실측 데이터를 말 한마디로! 건축HUB MCP 활용 가이드

부동산 중개, 감정평가, 시공, 리모델링, 그리고 도시개발 계획까지. 건축과 관련된 모든 비즈니스의 첫걸음은 언제나 "건축물대장"과 "인허가 데이터"를 확인하는 데서 시작합니다. 대한민국 모든 건축물의 정밀 스펙이 공공데이터포털에 잠들어 있지만, API의 영문 컬럼, 복잡한 인증 절차, 페이지네이션 탓에 비전문가가 접근하기는 쉽지 않았습니다.

이러한 장벽을 허물고 공공 데이터를 말 한마디로 자유롭게 추출해 주는 솔루션이 등장했습니다. 바로 '건축HUB MCP (Model Context Protocol)'입니다. 이제 복잡한 절차 없이 AI 어시스턴트에서 자연어 명령어만 입력해 완벽한 실측 통계를 뽑아낼 수 있습니다.

프로젝트 소개

건축HUB MCP란 무엇인가요?

국가법령정보 MCP가 "법령"을 다루고 통계 MCP가 "통계 수치"를 처리한다면, 건축HUB MCP는 오직 대한민국 "건축물 실체 데이터"만을 전문적으로 다룹니다. 국토교통부 건축HUB의 공식 API 실측값만을 정확히 추출하여 보여주고, 실측이 없는 항목은 [NOT_FOUND] 처리하여 인공지능의 거짓말(환각 현상)을 원천 차단합니다.

별도 복잡한 환경 설정 없이, fly.io 원격 커넥터를 통해 URL 한 줄만 연동하면 Claude 웹, Cursor, VS Code 등에서 즉시 비즈니스 파트너로써 건축 데이터를 바로 활용할 수 있습니다.

출처: 국토교통부 건축HUB (공공데이터포털 data.go.kr) / 개발자: Chris

💡 건축HUB MCP의 7가지 핵심 도구

주소 한 줄만 있으면 find_region 도구를 통해 법정동 코드를 빠르게 얻고, 목적에 맞는 아래 7가지 강력한 전용 도구들을 즉각 구동할 수 있습니다.

도구 1

1. building_profile (용도지역 포함 한 필지 종합카드)

대지 정보와 해당 지역의 지구지구구역 법적 규제를 포함해 주용도, 구조, 규모, 건폐율/용적률, 세대수, 주차공간, 내진설계 및 에너지효율 정보까지 단 한 번의 조회로 완벽히 요약한 카드를 생성합니다.

"자양동 2-2번지 건물 정보 한눈에 보여줘"
→ building_profile(11215, 10500, bun=2, ji=2)

용도지역 정보가 없는 필지는 해당 정보를 생략하여 가독성을 높입니다. 만약 공식 데이터에 건폐율/용적률이 비어 있다면 면적 기반으로 직접 계산을 진행하여 추정값과 실측값을 완벽하게 구분해서 알려줍니다.

도구 2

2. building_floors (층별 구성 스택)

건축물의 층별개요 정보를 호출하여 옥탑부터 지상, 지하층 순서대로 층별 용도와 구체적인 면적을 보기 좋게 쌓아서 나열해 줍니다. 리모델링, 용도변경, 상가 임대구성이나 소방/피난 검토 시 더없이 유용합니다.

"자양동 2-2번지 층별로 뭐가 있는지 보여줘"
→ building_floors(11215, 10500, bun=2, ji=2)

도구 3

3. district_stats (동 단위 건축물 통계 & 벤치마크)

개별 빌딩이 아니라 특정 법정동 전체의 부동산 분포를 분석할 때 빛을 발합니다. 표제부 정보를 일괄 수집해 총 연면적, 평균 층수, 사용승인 연대별 통계 및 노후도 분포를 분석해 냅니다. 여기에 "주용도별 평균 층수/용적률/높이의 중앙값"을 산출하는 규모 벤치마크도 함께 제공합니다.

"자양동 건축물 통계 내줘"
→ district_stats(11215, 10500)

도구 4

4. old_buildings (노후건축물 선별)

설정한 경과 연수에 부합하는 노후 건물을 찾아내어, 가장 오래된 순서대로 정렬해 줍니다. 노후 필지 발굴, 도시 정비사업 타당성 검토, 안전진단 대상 건물 필터링에 탁월합니다.

"자양동에서 40년 넘은 노후 건물 뽑아줘"
→ old_buildings(11215, 10500, min_age_years=40)

도구 5

5. price_history (공시가격 시계열)

해당 필지 호별로 무려 17개년 동안 누적된 공동주택/개별주택 가격 데이터를 모아 연도별 상승 흐름과 총증감률, 연평균 상승률(CAGR)을 명확하게 도출해 줍니다.

"자양동 24-28번지 공시가격 추이 보여줘"
→ price_history(11215, 10500, bun=24, ji=28)

공시가격은 실제 거래되는 시세가 아닙니다. 일반적으로 시세의 60~70% 선이며, 연도별 현실화율 정책의 변동 요인이 들어가 있으므로 이를 곧장 실거래가 상승률로 오독하면 안 됩니다.

도구 6

6. demolitions (철거멸실 현황 및 석면 여부)

철거멸실 대장에서 최근 집행된 순서대로 용도, 구조, 일정을 나열합니다. 특히 공사비 증가 및 주민 안전과 직결되는 석면 함유 부위(천장/바닥/단열/지붕 등)를 이모티콘 기호로 요약해 정밀하게 표시해 줍니다.

"자양동 2018년 이후 철거된 건물 보여줘"
→ demolitions(11215, 10500, since_year=2018)

도구 7

7. permits_pipeline (인허가 파이프라인)

건축 허가는 완전히 끝났으나 아직 실제 사용승인은 나지 않은 진행형 건축 프로젝트만 필터링합니다. 착공 여부 정보를 매칭하여 미착공/착공 상태를 구분하고, 향후 공급될 주택 및 건물 파이프라인을 예측하게 돕습니다.

"자양동 진행 중인 건축 인허가 보여줘"
→ permits_pipeline(11215, 10500, since_year=2024)

📋 제공되는 전체 11개 도구 일람

도구 이름	핵심 기능 및 활용 시나리오
find_region	기본 관할 주소 키워드를 기반으로 시군구/법정동 코드를 반환합니다.
building_profile	토지 규제(용도지역), 건물 스펙, 내진, 주차, 준공일을 합산해 종합 분석합니다.
building_floors	각 층별로 세분화된 용도 및 면적 정보를 스택 구조로 정돈합니다.
price_history	매물 호별 장기 공시가격 추이 및 연평균 상승률(CAGR)을 도출합니다.
district_stats	지정된 동 단위 전체 통계 및 주용도별 규모 벤치마크 수치를 연산합니다.
old_buildings	연식 노후도 기준에 맞춰 개발 대상 혹은 안전점검용 건물군을 정렬 추출합니다.
demolitions	지역 내 멸실 현황 추적 및 고위험 석면 시공 부위를 ⚠로 식별합니다.
permits_pipeline	승인 전 개발 단계인 미래의 공급 파이프라인 지표를 시계열로 수집합니다.
building_ledger	원천 대장 10종(표제부, 층별개요, 전유부 등)의 로우 데이터를 정밀 탐색합니다.
building_permit	건축인허가 17개 카테고리(대수선, 공영개발 등)의 상세 이력을 봅니다.
housing_permit	주택인허가 16개 카테고리(동별 구성, 부대복리시설 등) 대장을 제공합니다.

🎯 분야별 맞춤 사용 시나리오 & 프롬프트 예시

건축HUB MCP는 부동산 실무에 관계된 다양한 도메인에서 최고의 어시스턴트로 작동합니다. 본인의 직업에 맞추어 활용해 보세요.

• 공무원 및 공공기관 (정비계획 수립):
  "광진구 자양동 건축물 노후도랑 용도 구성 통계로 정리해줘" (district_stats)
  "자양동 2018년 이후 철거된 건물 석면 포함해서 보여줘" (demolitions)
• 건축사 및 시공사 (기획설계/대지분석):
  "자양동 2-2번지 용도지역이랑 건폐율·용적률 현황 한눈에 보여줘" (building_profile)
  "자양동 공동주택은 보통 몇 층에 용적률 얼마로 짓나 벤치마크 줘" (district_stats - 규모 벤치마크)
• 디벨로퍼 및 투자자 (사업성 스크리닝):
  "자양동에서 30년 넘은 단독주택 노후 필지 리스트업해줘" (old_buildings)
  "자양동 허가는 났는데 아직 사용승인 전인 신규 공급 건 보여줘" (permits_pipeline)
• 공인중개사 및 매수고객 (매물 중개):
  "자양동 2-2번지 건물 스펙 카드로 정리해줘, 고객 상담용이야" (building_profile)
  "자양동 2-2번지 층마다 무슨 업종이 들어와 있어?" (building_floors)
• 감정평가사 (물건 분석):
  "자양동 24-28번지 호별 공시가격 연도별 추이랑 상승률 뽑아줘" (price_history)
  "자양동 4-2번지 리버그린 연면적·대지면적·사용승인일 정리해줘" (building_profile)

※ 동명 뒤에 번지수를 입력해 주면 더욱 신속하게 검색 결과를 받아볼 수 있습니다.

🚀 아주 쉬운 1분 퀵스타트 가이드

원격 클라우드 서버가 활성화되어 운영 중이므로, 별도의 공공데이터포털 인증키 발급 없이 원격 URL 입력 한 번으로 즉시 시작할 수 있습니다.

Claude.ai 웹에서 바로 쓰기 (설치 불필요)

Claude 웹 서비스에 로그인한 뒤 다음 과정을 거쳐 등록합니다.

• 설정 페이지로 이동한 뒤 '커넥터(Connectors)' 탭을 클릭합니다.
• '커스텀 커넥터 추가(Add custom connector)'를 누르고 아래 주소를 입력합니다.

https://archhub-mcp.fly.dev/mcp

• 추가 완료 후 구성 항목에서 모든 도구의 상태를 "항상 사용(Always use)"으로 변경하면 완료됩니다!

Claude Code 및 개발자 툴 (Cursor, Desktop 등) 연동

개발자 환경에 로컬 혹은 설정 코드로 바인딩하려면 아래 설정을 그대로 복사해 입력하세요.

1. Claude Code 설정:

claude mcp add --transport http archhub https://archhub-mcp.fly.dev/mcp

2. Cursor / Windsurf / 원격 HTTP 지원 클라이언트 (mcpServers 구성):

{
  "mcpServers": {
    "archhub": { 
      "type": "http", 
      "url": "https://archhub-mcp.fly.dev/mcp" 
    }
  }
}

3. Claude Desktop (mcp-remote 어댑터 경유 - Node.js 18+):

{
  "mcpServers": {
    "archhub": { 
      "command": "npx", 
      "args": ["-y", "mcp-remote", "https://archhub-mcp.fly.dev/mcp"] 
    }
  }
}

🛠️ 개발자 영역: 로컬 실행 및 자가 구축 가이드

만약 외부 서버를 타지 않고 직접 로컬 컴퓨터에서 구동하고 싶다면 공공데이터포털의 건축HUB 디코딩 인증키가 있어야 합니다.

로컬 구동 방법 (stdio 프로토콜)

# 리포지토리 클론 및 이동
git clone https://github.com/chrisryugj/archhub-mcp && cd archhub-mcp

# 패키지 설치
pip install -e .

# 공공데이터포털 인증키 환경변수 등록 (Windows는 set 명령 사용)
export ARCHHUB_SERVICE_KEY="<발급받은 디코딩 인증키>"

# 실행
archhub-mcp

또는 uvx를 사용하여 설치 과정 없이 일회성으로 즉각 실행할 수 있습니다.

ARCHHUB_SERVICE_KEY=... uvx --from . archhub-mcp

클라우드 배포 (Fly.io 기반)

자신만의 원격 서버로 호스팅하려면 CLI를 이용해 간단히 실행합니다.

# 배포 설정 시작
fly launch --no-deploy

# 민감 정보인 인증키 주입
fly secrets set ARCHHUB_SERVICE_KEY="<디코딩 키>"
fly secrets set ARCHHUB_DAILY_CALL_CAP=9000  # 일일 호출 상한 설정 (선택 사항)

# 최종 배포
fly deploy

# 세션 일관성을 보장하기 위해 단일 머신 구조로 유지
fly scale count 1

⚠ 알아두어야 할 한계점과 주의사항

• 조회 무거움 현상: 법정동에 건축물이 아주 많을 때 (old_buildings, district_stats 등) 전체 페이지를 순회 스캔하므로 반응이 느릴 수 있습니다. (페이지당 100건, 최대 1만 개 행 순회 수집 후 절단 명시)
• 위반건축물 조회 불가능: API 레벨 자체에서 위반건축물 지정 여부 필드가 누락되어 있으므로 현재 조회할 수 없습니다.
• 개인 소유주 권한 배제: 정보 보호 정책상 건물 소유자 인적 정보 조회를 차단한 클린 공공 데이터만 제공합니다.
• 호출 트래픽 한계: 공공포털 자체의 동시 호출 제약이 있어, 필요에 따라 ARCHHUB_DAILY_CALL_CAP을 걸어두는 것을 권장합니다.

복잡한 행정 데이터를 완전히 새로운 차원의 지능형 인프라로 연결하는 건축HUB MCP.
지금 바로 Claude 커넥터에 연결해 스마트한 부동산 실무를 경험해보세요!

데이터 제공처: 국토교통부 건축HUB (공공데이터포털 data.go.kr)
깃허브 저장소: https://github.com/chrisryugj/archhub-mcp