Cadastral MCP

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

기능

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

Related MCP server: catastro_mcp_server

설치

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로 복사한 뒤 채웁니다.

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", "제곱미터당공시지가": "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를 마크다운으로 변환한 뒤 "기타/그 밖의 시설물" 행을 뽑습니다.

• 조례를 못 찾거나, 조문·별표 파싱에 실패하면 국가법령 상한이 항상 별도 행으로 함께 표시됩니다. 표에는 (법령)/(조례) 두 행이 나란히 나오고, 조례 조회가 실패하면 조례 행에 실패 사유가 표시됩니다.

• 응답의 지자체조례_조회 필드로 각 항목의 조회 성공 여부를 확인할 수 있습니다.

• korean-law-mcp를 이미 쓰고 있어도 별도 프로세스라 키를 공유할 수 없어 LAW_OC를 cadastral-mcp에도 따로 설정해야 합니다.

국가법령 상한 실시간 조회 (건폐율/용적률) — lib/national-law.ts

• 조례처럼 매 요청마다 법제처 API를 직접 호출해 국토계획법 시행령 제84조(건폐율)·제85조(용적률) 원문을 읽어옵니다 — 시행령이 개정돼도 코드 수정 없이 자동으로 최신 값이 반영됩니다.

• 조문 제목("건폐율" 키워드 등)은 다른 조문과 혼동될 수 있어(예: 제46조 제목에도 "건폐율"이 들어있음) 조번호(제84조/제85조)로 정확히 찾습니다. 조번호는 법 개정으로도 거의 바뀌지 않는 안정적 인용입니다.

• 용적률(제85조)은 조례와 달리 "X% 이상 Y% 이하" 범위로 규정돼 있어(구체적 수치는 지자체 조례가 그 범위 안에서 정함), 조례용 단일값 추출과는 별도로 범위를 그대로 추출합니다.

• 조경(건축법 시행령 제27조)은 조사해보면 조경 면적 %표가 아니라 "조경 조치 면제 대상" 목록입니다 — 국가법령 차원에는 전국 공통 조경 비율표 자체가 없고 전부 지자체 건축조례로 위임되어 있으므로, 녹지지역 면제 여부만 실시간 확인하고 그 외에는 정적 안내문("면적·용도별 기준 상이 — 조례 확인 필요")으로 대체합니다. 이건 낡은 값이 아니라 애초에 국가법령에 값이 없다는 사실을 안내하는 것입니다.

• 주차(주차장법 시행령 별표1)는 별표라 조문처럼 항/호/목으로 구조화되어 있지 않고 HWP에서 추출된 고정폭 텍스트라 안정적 파싱이 어려워, 원문을 직접 대조해 검증한 고정값(lib/zoning-standards.ts)을 계속 사용합니다.

• 실시간 조회가 실패하면(네트워크 오류 등) 항상 zoning-standards.ts의 검증된 고정값으로 조용히 폴백합니다. 응답의 국가법령_조회 필드로 실시간/고정값 여부를 확인할 수 있습니다.

search_national_law / get_national_law_text — 국가법령 자유 조회

• export_land_report_dxf 파이프라인이 내부적으로 쓰는 것과 같은 법제처 API 클라이언트(lib/national-law-api-client.ts)를 일반 질의용으로 노출한 도구입니다.

• search_national_law(query)로 법령명을 검색해 MST(법령일련번호)를 얻고, get_national_law_text(mst, jo?)로 조문을 조회합니다. jo 미지정 시 조문 목차(번호+제목)만 반환해 응답 크기를 줄이고, jo를 지정하면(예: "84", "제84조", "12의2") 해당 조문 전체 텍스트를 반환합니다.

• 판례·심결례·법률용어·조약 등은 다루지 않습니다 — target=law(법령) 한 종류만 구현했습니다. 그 범위를 넘어서는 법률 조사가 필요하면 korean-law-mcp를 함께 쓰세요(런타임 의존성은 없습니다 — 아래 "korean-law-mcp와의 관계" 참고).

korean-law-mcp와의 관계

cadastral-mcp는 korean-law-mcp를 참조했을 뿐 런타임 의존성이 전혀 없습니다 — package.json에도 없고, 설치·실행 시 korean-law-mcp가 켜져 있을 필요도 없습니다. 법제처 Open API(대한민국 정부가 공개한 표준 API — target/OC/MST 같은 파라미터 규약은 정부가 정한 것이지 korean-law-mcp의 창작물이 아닙니다)를 cadastral-mcp가 직접 호출합니다.

다만 법제처 API는 UA/Referer 헤더가 없으면 거부하고 클라우드 IP에서는 JS 리다이렉트로 위장한 안티봇 페이지를 주는 까다로운 특성이 있는데, 이 우회 로직(lib/law-antibot.ts)만은 korean-law-mcp가 먼저 해결해둔 것을 MIT 라이선스 하에 가져다 썼습니다 — LICENSE 파일에 출처를 명시해 두었습니다. 이 저장소가 다루는 범위(자치법규 조례 + 국가법령 조문, 판례·법률용어 등은 제외)는 korean-law-mcp보다 훨씬 좁고, 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] 참조 — 세부 기준표 자동추출 실패"로 조번호·별표번호까지만 안내합니다(수치를 지어내지 않음).

• 국가법령 건폐율·용적률 실시간 조회(lib/national-law.ts)는 국토계획법 시행령 제84·85조라는 조번호가 안정적이라는 전제로 동작합니다. 법 개정으로 이 조문 자체가 삭제·이동되는 극단적인 경우 실시간 조회는 실패하지만(→ 고정값으로 조용히 폴백), 고정값 자체가 시행령 개정을 자동 반영하진 못합니다.

• 국가법령 주차 기준(주차장법 시행령 별표1)은 실시간 조회를 구현하지 않았습니다 — 별표는 조문과 달리 항/호/목 구조가 없는 HWP 추출 고정폭 텍스트라 표 경계를 안정적으로 구분하기 어렵습니다. 원문을 직접 대조해 검증한 고정값(PARKING_STANDARD_CELL)을 계속 사용합니다.

개발

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

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