VWorld Local MCP Server

이 프로젝트는 부동산 개발 타당성 검토 업무 등에서 특정 필지의 위치, 경계, 지적정보, 용도지역지구, 공시지가 정보를 빠르게 조회할 수 있도록 VWorld Open API를 감싸는 로컬 MCP(Model Context Protocol) 서버입니다.

⚠️ 중요 이용 정책 제약 사항 (필독)

VWorld 서비스 이용 약관에 따라 아래 사항을 엄격히 준수해야 합니다.

1. 일일 요청 한도: Geocoder API 및 Reverse Geocoder API는 일일 최대 30,000건의 요청으로 제한됩니다.

2. 저장 및 캐싱 금지: Geocoder(vworld_geocode) 및 Reverse Geocoder(vworld_reverse_geocode)를 통해 조회한 응답 결과(주소 및 좌표 데이터)를 데이터베이스나 로컬 스토리지에 캐싱하거나 영구히 저장하는 행위는 금지되어 있습니다. 본 서버는 이를 준수하여 모든 조회를 실시간(Real-time)으로 수행합니다.

Related MCP server: Korea Building Register MCP

🛠️ 설치 및 설정 방법

1. 요구 사항

• Python 3.11 이상

• VWorld Open API 인증키 (https://www.vworld.kr 에서 회원가입 후 발급)

  • 중요: 로컬 테스트 환경을 지원하기 위해 본 서버는 API 요청 시 domain=localhost 매개변수를 전송합니다. 따라서 VWorld 인증키 발급 시 등록 도메인에 반드시 **localhost**가 포함되어 있어야 합니다.

2. 설치

프로젝트 디렉토리로 이동하여 의존성 패키지를 설치합니다. 가상환경(venv) 사용을 권장합니다.

# 가상환경 생성 및 활성화 (Windows PowerShell 예시)
python -m venv .venv
.venv\Scripts\Activate.ps1

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

3. 환경 변수 설정

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

copy .env.example .env

.env 파일 내용:

VWORLD_API_KEY=YOUR_VWORLD_API_KEY_HERE

🌍 배포 가이드라인 및 주의사항 (해외 IP 차단)

☁️ Cloudtype (한국 IP 호스팅) 배포 가이드

해외 IP 차단 문제를 해결하기 위해, 한국 IP를 기본 제공하는 Cloudtype 배포를 권장합니다. 저장소에 이미 Procfile이 포함되어 있어, 별도의 서버 코드 수정 없이 바로 배포할 수 있습니다.

1. GitHub 연동: Cloudtype 콘솔에서 새 프로젝트를 생성하고 본 GitHub 저장소를 연결합니다.

2. 환경 변수 설정: 배포 설정 화면에서 다음 환경 변수를 추가합니다.

   • VWORLD_API_KEY: 발급받은 VWorld API 키

   • VWORLD_DOMAIN: 새로 생성된 Cloudtype 앱 도메인 (예: my-app.cloudtype.app)

   • (참고: PORT 환경 변수는 Cloudtype이 자동 주입하므로 따로 설정할 필요 없습니다.)

3. 배포 후 MCP 접속:

   • Claude Desktop 또는 MCP 클라이언트에 입력할 접속 URL은 다음과 같습니다:

   • https://<새로 발급된 앱주소>.cloudtype.app/sse

• 프록시(Proxy) 우회 (옵션): 불가피하게 해외 클라우드를 유지해야 할 경우, 한국 IP를 가진 프록시 서버를 구축한 뒤 환경 변수 VWORLD_PROXY_URL을 설정하면 MCP 서버가 이를 경유하여 통신할 수 있습니다.

🚀 실행 및 검증 (MCP Inspector)

MCP SDK에 포함된 인스펙터를 사용해 서버의 동작 및 도구(Tool) 호출을 수동으로 검증할 수 있습니다.

npx @modelcontextprotocol/inspector python server.py

실행 후 브라우저가 열리면, 제공되는 도구들을 하나씩 테스트해볼 수 있습니다.

🛠️ 제공하는 MCP 도구(Tool) 목록 및 사용 예시

1. vworld_search

• 설명: 주소/장소/지번 통합 검색을 수행합니다.

• 매개변수:

  • query (str): 검색할 텍스트 (예: "서울시청", "세종대로 110")

  • category (Literal["address", "place"]): 검색 범주 ("address": 주소 검색, "place": 장소/POI 검색)

• 반환: 검색된 결과 목록 및 각 결과의 위/경도 좌표

2. vworld_geocode

• 설명: 한글 주소를 경위도 좌표로 변환합니다. (저장/캐싱 금지)

• 매개변수:

  • address (str): 변환할 주소 (예: "세종대로 110")

  • address_type (Literal["road", "parcel"]): 주소 체계 구분 ("road": 도로명주소, "parcel": 지번주소)

• 반환: 좌표 {"lat": 위도, "lon": 경도} 및 약관 주의사항 문구

3. vworld_reverse_geocode

• 설명: 경위도 좌표를 주소로 역지오코딩합니다. (저장/캐싱 금지)

• 매개변수:

  • lat (float): 위도 (예: 37.5666805)

  • lon (float): 경도 (예: 126.9784147)

• 반환: 해당 좌표에 매칭되는 도로명 및 지번 주소 목록

4. vworld_get_parcel

• 설명: PNU(19자리 필지고유번호)를 기준으로 연속지적도(LP_PA_CBND_BUBUN) 레이어를 조회하여 필지 경계 및 지번 정보를 반환합니다.

• 매개변수:

  • pnu (str): 19자리 필지 고유 번호

• 반환: 필지 경계의 GeoJSON(geometry) 및 지번, 본번, 부번 등의 속성정보

5. vworld_get_landuse_zone

• 설명: 용도지역지구 등 도시계획 관련 레이어를 조회합니다. (WFS API)

• 매개변수:

  • pnu (str, optional): 19자리 PNU. 제공 시 필지 경계의 중심점을 자동 계산하여 조회합니다.

  • lat (float, optional): 위도.

  • lon (float, optional): 경도.

• 설명: PNU 혹은 위경도 좌표를 통해 4대 용도지역(lt_c_uq111 ~ lt_c_uq114) 레이어를 공간적(INTERSECTS)으로 검색하여 겹치는 용도지역 명칭 및 코드를 반환합니다.

6. vworld_get_individual_price

• 설명: 국토교통부 토지특성 속성조회 API를 통해 특정 필지의 개별공시지가를 조회합니다.

• 매개변수:

  • pnu (str): 19자리 PNU

• 설명: 현재 연도부터 순차적으로 최근 3년까지(예: 2026 -> 2025 -> 2024 -> 2023) 폴백(Fallback) 조회를 시도하여 가장 최신의 공시지가 정보(원/㎡)를 반환합니다.

⚙️ Antigravity mcp_config.json 등록 예시

이 로컬 MCP 서버를 Antigravity 환경에 연결하려면, 아래 설정을 mcp_config.json에 추가하십시오. (상황에 따라 command와 args의 파이썬 실행 바이너리 및 server.py의 절대 경로를 맞춰야 합니다.)

{
  "mcpServers": {
    "vworld-mcp": {
      "command": "python",
      "args": [
        "c:/Users/10564/Documents/VWorld_MCP/server.py"
      ],
      "env": {
        "VWORLD_API_KEY": "발급받은_VWORLD_API_키"
      }
    }
  }
}

또는 가상환경(venv)을 적용하여 실행하려는 경우 아래와 같이 가상환경 내 Python 경로를 지정할 수 있습니다.

{
  "mcpServers": {
    "vworld-mcp": {
      "command": "c:/Users/10564/Documents/VWorld_MCP/.venv/Scripts/python.exe",
      "args": [
        "c:/Users/10564/Documents/VWorld_MCP/server.py"
      ],
      "env": {
        "VWORLD_API_KEY": "발급받은_VWORLD_API_키"
      }
    }
  }
}