BDLedger Server

국토교통부 건축HUB 「건축물대장정보 서비스」(공공데이터포털 data.go.kr)의 OpenAPI를 래핑하여, 다양한 건축물대장 정보를 조회할 수 있는 단일 파일 기반 파이썬 MCP(Model Context Protocol) 서버입니다.

이 서버는 Claude AI나 Antigravity IDE와 같은 MCP 지원 클라이언트와 연동하여 LLM이 실시간으로 건축물 속성 정보(면적, 구조, 용도, 내진설계, 주택가격 등)를 질의하고 분석할 수 있도록 돕습니다.

---

⚠️ 데이터 활용 및 트래픽 정책 주의사항

1. 일일 호출 한도: 공공데이터포털 서비스 키 활용 신청 시 지정된 일일 호출 한도(기본 계정당 일 1,000~10,000회 등)를 초과하지 않도록 주의해야 합니다.
2. 개인정보 보호: 이 API는 개인정보 보호 정책에 따라 건축물의 소유주명, 주민번호 등 민감한 개인정보는 일체 반환하지 않습니다.
3. PK 체계 변경 주의: 기존 건축데이터 민간개방시스템에서 '건축HUB'로 데이터가 통합 및 이관됨에 따라 대장 고유 식별자인 **PK(기본키)**가 변경되었습니다. 이전 PK와 호환이 필요하다면 공공데이터포털에서 배포하는 PK 전환 규칙 문서를 참고하십시오.
4. 키 인코딩 이슈: 공공데이터포털에서 발급받은 인증키 중 **일반 인증키(Decoding)**를 사용해야 이중 인코딩 문제가 발생하지 않습니다. 본 서버는 자체적으로 serviceKey를 디코딩하여 httpx에 안전하게 넘기는 로직을 내장하고 있어, 이중 인코딩 관련 에러(SERVICE_KEY_IS_NOT_REGISTERED_ERROR)를 원천적으로 예방합니다.

---

🚀 설치 및 실행 방법

1. 요구사항

• Python 3.11 이상

2. 가상환경 설정 및 패키지 설치

프로젝트 루트 폴더에서 가상환경을 만들고 의존성을 설치합니다.

# 가상환경 생성
python -m venv .venv

# 가상환경 활성화 (Windows PowerShell)
.venv\Scripts\Activate.ps1

# 의존성 패키지 설치
pip install -r requirements.txt

3. 환경 변수 설정

.env.example 파일을 복사하여 .env 파일을 생성하고 발급받은 공공데이터포털 API 키를 입력합니다.

cp .env.example .env

.env 파일 내용:

BLDRGST_API_KEY=발급받은_일반_인증키_Decoding_값
PORT=8080
# BLDRGST_PROXY_URL=http://프록시서버주소 (필요한 경우만)

4. 로컬 실행 (stdio 방식)

로컬 데스크톱 클라이언트(예: Claude Desktop, Antigravity IDE)와 표준 입출력(stdio)으로 통신할 때 실행하는 명령어입니다.

python server.py stdio

5. 원격/웹 실행 (SSE 방식)

클라우드 플랫폼(예: Render, Cloudtype, Docker 등)에 배포하거나 웹 기반 클라이언트와 SSE(Server-Sent Events)로 통신할 때 사용합니다.

# SSE 모드로 서버 시작
python server.py sse
# 또는 Procfile을 통해 실행

---

🔍 MCP Inspector를 활용한 검증

서버가 제대로 작동하는지, 등록된 도구(Tools) 스키마가 잘 로드되는지 확인하기 위해 MCP Inspector를 실행해 검증할 수 있습니다.

npx @modelcontextprotocol/inspector python server.py

---

🛠️ 제공하는 MCP 도구(Tools) 목록

사용자는 주로 19자리 **PNU(필지 고유번호)**를 입력하여 조회합니다. 10자리 행정코드(시군구5+법정동5)와 지번 등을 알고 있다면 개별적으로 입력하여 오버라이드할 수도 있습니다. 주의: PNU 필지구분 기호 1(일반대지)은 API 요청 시 0(대지)으로, 2(산)는 1(산)로 내부에서 자동 변환되어 전달됩니다.

도구명	공공데이터 API명	설명 / 주요 반환 필드
br_get_basis_ouln	getBrBasisOulnInfo	기본개요: 건물의 기본 개요 및 위치 정보 조회 - mgmBldrgstPk, platPlc, bldNm, regstrKindCdNm
br_get_recap_title	getBrRecapTitleInfo	총괄표제부: 대지 내 모든 동의 총괄 내역 조회 - platArea, archArea, totArea, bcRat, vlRat, totPkngCnt
br_get_title	getBrTitleInfo	표제부: 개별 동의 현황(주용도, 층수, 내진적용 여부 등) 조회 - dongNm, grndFlrCnt, mainPurpsCdNm, rserthqkDsgnApplyYn
br_get_floor_ouln	getBrFlrOulnInfo	층별개요: 건물의 각 층별 면적, 구조, 주용도 조회 - dongNm, flrNoNm, area, mainPurpsCdNm, strctCdNm
br_get_atch_jibun	getBrAtchJibunInfo	부속지번: 대표 지번 외의 부속 지번(관련 지번) 현황 조회 - atchBun, atchJi, atchPlatGbCd
br_get_expos_pubuse_area	getBrExposPubuseAreaInfo	전유공용면적: 집합건물 각 호의 전용면적 및 공용면적 조회 - hoNm, exposPubuseGbCdNm (전유/공용), area
br_get_wclf	getBrWclfInfo	오수정화시설: 정화조 형식, 용량(인용/루베) 등 규격 조회 - modeCdNm, capaLube, capaPsper
br_get_house_price	getBrHsprcInfo	주택가격: 공동주택(아파트, 빌라 등)의 공시가격 조회 - hsprc, bylotCnt, crtnDay
br_get_expos	getBrExposInfo	전유부: 집합건물의 호별 개요 및 층/호 위치 조회 - dongNm, flrNo, hoNm, mgmBldrgstPk
br_get_jijigu	getBrJijiguInfo	지역지구구역: 지정된 용도지역/용도지구/용도구역 정보 조회 - jijiguCdNm, jijiguGbCdNm, reprYn
br_health_check	-	연결성 진단: API 키 유효성 및 국토부 서버 연결 상태/응답속도 점검

---

⚙️ Antigravity mcp_config.json 설정 예시

Antigravity IDE 또는 VSCode MCP 설정에 등록하여 사용할 때 아래 JSON 설정을 추가하십시오.

{
  "mcpServers": {
    "building-ledger-mcp": {
      "command": "python",
      "args": [
        "C:/Users/10564/Documents/BDLedger_MCP/server.py",
        "stdio"
      ],
      "env": {
        "BLDRGST_API_KEY": "여러분의_디코딩된_공공데이터포털_API_키"
      }
    }
  }
}

주의: server.py 경로가 올바른지 다시 한번 확인하십시오.