Cadastral MCP

브이월드(국토교통부) Open API 기반 토지이용계획 조회 + 지적도 DXF 내보내기 MCP 서버.

기능

도구	설명
get_land_use_plan	지번 주소로 토지대장(지목·면적·소유구분) + 용도지역/지구/구역 + 개별공시지가 통합 조회
get_land_use_plan_by_pnu	PNU(19자리)로 위와 동일 조회
export_cadastral_dxf	지번 주소로 필지 경계(+주변 필지)를 DXF 파일로 내보내기
export_cadastral_dxf_by_pnu	PNU(19자리)로 위와 동일 내보내기
export_land_report_dxf	지번 주소로 요청정보(표)+토지이용계획+지적도(XCLIP 크롭)를 한 페이지 DXF로 내보내기
export_land_report_dxf_by_pnu	PNU(19자리)로 위와 동일 내보내기

모든 기능이 참고용입니다 — 법적 효력이 있는 「토지이용계획확인서」·지적측량성과도를 대체하지 않습니다. 정확한 확인은 토지이음(eum.go.kr) 또는 관할 행정청에 문의하세요.

설치

npm install
npm run build

export_land_report_dxf(한 페이지 리포트, XCLIP 크롭)를 쓰려면 Python 3 + ezdxf도 필요합니다:

pip install ezdxf

Python이 여러 개 설치돼 있어 자동탐지(python3 → python → py)가 ezdxf 없는 쪽을 먼저 찾으면, .env에 CADASTRAL_PYTHON으로 정확한 경로를 지정하세요. export_cadastral_dxf(지도만 내보내는 도구)는 Python 없이도 그대로 동작합니다.

VWorld API 키 발급

1. vworld.kr 가입 후 로그인
2. 오픈API 인증키 신청 페이지에서:
   • 서비스URL: 이 서버를 실행할 도메인/IP (예: http://localhost, 서버 배포 시 실제 도메인)
   • 활용API: 아래 항목 체크 필수
     • 검색 API — 주소 → PNU 변환
     • 2D데이터 API — 지적 필지 경계 좌표, 개별공시지가(폴리곤 속성)
     • 국가중점 API — 토지대장, 용도지역/지구 (ned/data/* 엔드포인트가 이 카테고리)
     • WMS/WFS API — 필수는 아니지만 함께 체크해두면 무방
3. 승인은 즉시~수 시간 소요될 수 있습니다.

중요: 검색 API는 도메인 값 없이도 동작하지만, 2D데이터·국가중점 API는 요청에 domain 파라미터가 없거나 키 신청 시 등록한 서비스URL과 다르면 INCORRECT_KEY 에러가 발생합니다. 아래 VWORLD_DOMAIN을 반드시 서비스URL과 동일하게 맞추세요.

환경변수

.env.example을 .env로 복사한 뒤 채웁니다.

변수	필수	설명
VWORLD_KEY	필수	VWorld 오픈API 인증키
VWORLD_DOMAIN	필수에 가까움	키 신청 시 등록한 서비스URL과 정확히 일치해야 함. 없으면 2D데이터·국가중점 API가 INCORRECT_KEY로 실패
DXF_OUTPUT_DIR	선택	DXF 파일 저장 경로 (기본값: ./output)
CADASTRAL_PYTHON	선택	export_land_report_dxf의 XCLIP 크롭에 쓸 Python 실행 파일 경로. 미지정 시 python3/python/py 자동탐지
LAW_OC	선택	법제처 Open API 인증키. export_land_report_dxf가 필지 소재 지자체 조례에서 건폐율/용적률/조경 기준을 자동 조회하는 데 사용. 없으면 국가법령 상한으로 대체

MCP 클라이언트 연결 (예: Claude Desktop)

claude_desktop_config.json:

{
  "mcpServers": {
    "cadastral-mcp": {
      "command": "node",
      "args": ["절대경로/cadastral-mcp/build/index.js"],
      "env": {
        "VWORLD_KEY": "발급받은키",
        "VWORLD_DOMAIN": "키 신청 시 등록한 서비스URL"
      }
    }
  }
}

도구 상세

get_land_use_plan / get_land_use_plan_by_pnu

• 입력: address(또는 pnu), stdrYear(선택, 개별공시지가 기준연도, 기본값 올해)
• 출력 예시:

{
  "PNU": "5211312000100770003",
  "토지대장": { "지목": "답", "면적": "4470", "소유구분": "개인" },
  "용도지역지구": ["자연재해위험개선지구", "가축사육제한구역", "생산녹지지역"],
  "개별공시지가": [{ "기준연도": "2026", "공시지가원per제곱미터": "191300" }]
}

export_cadastral_dxf / export_cadastral_dxf_by_pnu

• 입력: address(또는 pnu), crs(선택, 기본 EPSG:5186), includeNeighbors(선택, 기본 true), bufferMeters(선택, 기본 50)
• 대상 필지는 대상 필지 경계상자를 bufferMeters만큼 확장한 범위 안의 모든 필지(공공도로 포함)를 함께 조회해 그립니다.
• 사용자가 범위(bufferMeters)를 지정하지 않았다면, 호출 전에 몇 미터로 할지 먼저 물어보고 진행하세요. (도구 설명에도 이 지침이 포함되어 있어 MCP 클라이언트가 자동으로 인지합니다.)
• DXF 레이어 구성:
  • TARGET_PARCEL / TARGET_LABEL — 대상 필지 경계(굵은 빨강 선) + 지번 라벨
  • NEIGHBOR_PARCELS / NEIGHBOR_LABEL — 주변 필지 경계(얇은 파랑 선) + 지번 라벨
  • SOURCE_NOTE — 출처/면책 문구(초록)
• 좌표계는 VWorld가 서버단에서 투영 변환해 반환하므로(EPSG:5186/5174 등) 별도 좌표변환 라이브러리 없이 그대로 DXF 좌표로 사용합니다.

export_land_report_dxf / export_land_report_dxf_by_pnu

• 입력: address(또는 pnu), crs/includeNeighbors/bufferMeters(기본값은 export_cadastral_dxf와 동일), stdrYear(선택)
• 한 페이지 레이아웃(돋움 폰트, 흰 다이아몬드 아이콘 + 초록 제목 + 노랑 이중밑줄 타이틀), 좌/우상단 모두 표 형식:
  • 좌측: 요청 정보 표 — 대지위치·대지면적·지목·지역/지구는 VWorld 데이터. 최대건폐율·최대용적률·조경계획·주차계획은 국가법령 상한과 필지 소재 지자체 조례(도시계획조례·건축조례·주차장조례) 값을 각각 별도 행으로 나란히 표시(아래 "지자체 조례 자동 조회" 참고). 전면도로·접도길이는 데이터 소스가 없어 -
  • 우상단: 토지이용계획 — 법정동·지번·지목·면적·소유구분·지역/지구·개별공시지가 7행 표
  • 우하단: 지적도 — CADASTRAL_MAP 블록으로 그린 뒤, 패널 테두리를 경계로 **실제 AutoCAD XCLIP(SPATIAL_FILTER)**을 적용해 박스 밖으로 나가는 필지(도로 등)를 진짜로 잘라냅니다
• XCLIP은 Python(ezdxf) 서브프로세스로 적용됩니다. Python/ezdxf가 없으면 클립 없이(블록은 그대로) 파일이 만들어지고, 응답의 지적도_XCLIP크롭 필드에 실패 사유가 표시됩니다.
• 표 셀 값은 줄이지 않고 전부 보여줍니다 — 짧은 값은 한 줄, 긴 값(조경계획·주차계획의 조례 원문 등)은 자동 줄바꿈되면서 그 행만 세로로 커집니다(다른 행에서 높이를 나눠 빌려오는 방식이라 표 전체 높이는 그대로).

지자체 조례 자동 조회 (건폐율/용적률/조경/주차)

• 법정동명에서 시·군 이름을 추출해 법제처 Open API로 "{시} 도시계획 조례"/"{시} 건축 조례"/"{시} 주차장 조례"를 검색하고, 전체 조문에서 "건폐율"+21개 용도지역명 같은 키워드로 해당 조문을 직접 찾습니다(조문번호가 목차 순서와 안 맞는 경우가 많아 번호를 추측하지 않음).
• 주차 기준은 조문 본문이 아니라 별표(HWP/PDF 첨부파일)로 위임된 경우가 많아, 조문에서 "별표N" 인용을 발견하면 별표 목록을 검색해 실제 파일을 다운로드하고 kordoc(korean-law-mcp가 별표 파싱에 쓰는 것과 동일한 라이브러리)으로 HWP/HWPX/PDF를 마크다운으로 변환한 뒤 "기타/그 밖의 시설물" 행을 뽑습니다.
• 조례를 못 찾거나, 조문·별표 파싱에 실패하면 국가법령 상한(국토계획법 시행령 제84·85조, 건축법 시행령 제27조, 주차장법 시행령 별표1 — lib/zoning-standards.ts)이 항상 별도 행으로 함께 표시됩니다. 표에는 (법령)/(조례) 두 행이 나란히 나오고, 조례 조회가 실패하면 조례 행에 실패 사유가 표시됩니다(국가법령 상한 행은 항상 정상 표시).
• 응답의 지자체조례_조회 필드로 각 항목의 조회 성공 여부를 확인할 수 있습니다.
• korean-law-mcp를 이미 쓰고 있어도 별도 프로세스라 키를 공유할 수 없어 LAW_OC를 cadastral-mcp에도 따로 설정해야 합니다.

데이터 출처

• 지적 경계·지번·공시지가: VWorld 2D데이터 API (req/data, layer LP_PA_CBND_BUBUN — 연속지적도). 원본은 국토교통부/한국국토정보공사(LX)가 관리하는 연속지적도(수치지적) 데이터이며, VWorld가 이를 REST API로 서비스합니다. shp 파일을 직접 읽지 않습니다.
• 토지대장·용도지역지구: VWorld 국가중점(NED) API (ned/data/ladfrlList, ned/data/getLandUseAttr)
• 개별공시지가: VWorld 국가중점(NED) API (ned/data/getIndvdLandPriceAttr)

알려진 한계

• 홀(구멍)이 있는 도넛형 필지는 로직상 지원하지만 실사용 케이스로 검증되지 않았습니다.
• DXF는 참고용이며 법적 효력이 있는 지적측량성과도가 아닙니다.
• VWorld 데이터 갱신 주기(보통 월 단위)를 따르므로 실시간 최신 상태가 아닐 수 있습니다.
• export_land_report_dxf의 XCLIP은 ezdxf.audit() 구조 검증(오류 0건, has_extension_dict/has_clipping_path 정상)에 더해, 실제 AutoCAD에서 열어 정상 작동(박스 밖 필지 크롭)까지 확인했습니다.
• 시스템에 Python이 여러 개 설치돼 있고 그중 ezdxf가 없는 것이 먼저 잡히면 CADASTRAL_PYTHON으로 경로를 지정해야 합니다.
• 지자체 조례 자동 조회는 "{시} 도시계획 조례"/"{시} 건축 조례"/"{시} 주차장 조례" 이름 패턴과 21개 용도지역 표 형식(예: "생산녹지지역：100분의 20")에 맞춰 파싱합니다. 지자체마다 조례명·표기 방식이 달라 일부 지역은 매칭에 실패할 수 있으며, 그 경우 국가법령 상한 행만 표시됩니다.
• 별표 HWP 파싱(kordoc)은 문서 포맷이 다양해 100% 성공을 보장하지 않습니다. 실패 시 "[별표N] 참조 — 세부 기준표 자동추출 실패"로 조번호·별표번호까지만 안내합니다(수치를 지어내지 않음).

개발

npm run watch      # TypeScript watch 빌드
npm run typecheck  # 타입 체크만
npm test           # vitest

테스트는 네트워크 호출 없이 순수 로직만 검증합니다 — 지자체 조례 파싱(local-ordinance.test.ts, 실사용 중 발견한 버그 위주: 값 뒤에 다음 항목번호가 공백 없이 붙는 케이스, 조번호를 title이 아니라 content에서 뽑는 것 등)과 국가법령 상한 조회(zoning-standards.test.ts). API 연동 자체(VWorld/법제처/XCLIP)는 실제 키로 수동 검증했습니다.