🇰🇷 Korean Land MCP — v2.0

V-World API-based Land & Urban Planning Spatial Information MCP Server Using the Ministry of Land, Infrastructure and Transport's V-World Open API as a backend, this is a Model Context Protocol server that allows AI to query zoning, land use districts, land use zones, district unit plans, urban planning facilities, and other legal designations—information that was previously manually checked on Land-eum (eum.go.kr)—using natural language.

A spatial layer MCP that pairs with korean-law-mcp (legal text). When used together, they allow you to connect "Where does this parcel belong?" to "What does the relevant law/ordinance permit/restrict?" in a single line of natural language.

✨ v2.0 Architectural Principles

1. V-World API Only. No other commercial APIs, scraping, or mock data.

2. Honest Failure. If V-World returns a 500 for a specific layer, it is exposed as-is in layer_errors. Never filled with fake data.

3. Separation of Concerns from korean-law-mcp. This MCP only answers "Where does it belong spatially?". Clause interpretation is handled by korean-law-mcp.

4. Automatic Detection of Priority Delegation under Article 76(5) of the National Land Planning Act. If a parcel is affected by Agricultural Promotion Zones, Conservation Mountainous Districts, Water Source Protection Zones, or National Industrial Complexes, it provides a priority_delegation_hint indicating "which law to prioritize over the National Land Planning Act Enforcement Decree Table."

Related MCP server: Korea Building Register MCP

🛠️ Provided Tools (7)

Includes discover_tools to explore the tool catalog via natural language.

📡 V-World Layer Coverage

• Zoning: LT_C_UQ111/112/113/114 (Urban, Management, Agriculture, Nature Conservation)

• Land Use Districts/Zones: LT_C_UQ121~130, LT_C_UD801, LT_C_UQ162

• District Unit Plans/Permit Restrictions: LT_C_UPISUQ161, LT_C_UPISUQ171

• Urban Planning Facilities: LT_C_UPISUQ151~159

• Other Legal Designations: Farmland (AGRIXUE) · Forestry (UF) · Industrial Complex (WGISIE*, DAM*) · Water Quality (UM, WGISARWET) · Livestock (UM000) · Cultural Heritage (UO) · Natural Park (WGISNP*) · Special Districts (UO/UJ/UH/UB) · Housing Improvement (UD) · Disaster (UP) · Marine (TFISMPA, WGISRE*) · Aviation (AIS*)

• Parcel/Building: LP_PA_CBND_BUBUN, LT_C_BLDGINFO, A2SM_LNDPRCPS

🚀 Quick Start

1. Setup in One Go

git clone https://github.com/UrbanWatcherKr/korean-land-mcp.git
cd korean-land-mcp
npm run setup

npm run setup executes npm install → npm run build → interactive configure. During the configure step, it asks for your V-World API key and domain, and automatically generates the .env file.

V-World API Key Issuance: https://www.vworld.kr/dev/v4api.do (Login → Open API → Issue Authentication Key, free). For local development, register the domain as localhost.

2. Re-configure

If you want to change the API key or domain at any time:

npm run configure

3. Register with Claude Desktop / Claude Code

After configuration, it prints the JSON block to paste into your terminal. Or manually:

{
  "mcpServers": {
    "korean-land": {
      "command": "node",
      "args": ["/absolute/path/to/korean-land-mcp/dist/server.js"],
      "env": {
        "VWORLD_API_KEY": "your_real_key_here",
        "VWORLD_DOMAIN": "localhost"
      }
    }
  }
}

💬 Usage Examples

• "Tell me the zoning for 680 Naegi-ri, Poseung-eup, Pyeongtaek-si, Gyeonggi-do" → get_zoning

• "Check if Article 76(5) priority delegation applies to this parcel" → get_other_law_designations

• "Are there any urban planning facilities encroaching or adjacent within a 50m radius?" → `get_urban_facility({ radius_m: 50 })"

• "Analyze this lot number and tell me the next step for korean-law" → analyze_parcel

🧭 Workflow with korean-law-mcp

사용자: "이 지번에 공장 지을 수 있어?"
  ↓
korean-land-mcp · analyze_parcel
  ↓ (용도지역=일반공업, 산업단지=아산포승, 우선위임=산업입지법)
korean-law-mcp · search_law("산업입지법")
  ↓
korean-law-mcp · get_law_text(산업입지법 제33조)
  ↓
결론 + 원문 근거

🗂️ Project Structure

src/
├── server.ts                          # MCP stdio 엔트리, 7개 도구 등록
├── lib/
│   ├── vworld.ts                      # V-World HTTP 클라이언트 (5xx 재시도 1회)
│   ├── overlays.ts                    # 병렬 레이어 쿼리 + POINT/BOX 필터
│   ├── resolve.ts                     # 주소/지번/PNU 해석
│   └── jimok.ts                       # 지목 코드 28종 매핑
└── tools/
    ├── resolve_parcel.ts
    ├── get_zoning.ts
    ├── get_district_plan.ts
    ├── get_urban_facility.ts
    ├── get_other_law_designations.ts
    ├── get_land_attributes.ts
    └── analyze_parcel.ts

🧪 Testing

Unit Tests (Pure functions, no API key required):

npm test

Live smoke test (Actual V-World calls, requires VWORLD_API_KEY):

# 단일 지번 디버그
npx tsx tests/live/smoke-polygon.ts "서울특별시 마포구 연남동 229-1"

# 3개 픽스처 회귀 테스트 (스냅샷 비교)
npx tsx tests/live/smoke-fixtures.ts

# 스냅샷 갱신 (V-World 데이터 변경 시)
npx tsx tests/live/smoke-fixtures.ts --update

Fixtures: Urban residential area (Yeonnam-dong), Agriculture/Forestry area + priority delegation (Sechul-ri), Mixed zoning + urban development (Galmae-ri).

⚠️ Known Limitations

• Point-based Determination: The default query sends one parcel center point to V-World. Since it is not a parcel polygon intersection, cases on the boundary may be missed. The radius_m in get_urban_facility mitigates this with a BOX filter, but final determination of "encroachment" vs "adjacency" requires re-verification of polygon intersection by the user or a responsible official.

• V-World Layer Outages: Some layers intermittently return HTTP 500. If it fails after one 5xx retry, it is exposed in layer_errors, and the results for the remaining layers are returned normally.

• Local Ordinances Not Included: This MCP only covers spatial layers. Local urban planning ordinances must be queried separately via korean-law-mcp or the Ministry of Government Legislation's local autonomous law API.

📜 License

MIT License.

🤝 Contributing

Issues and PRs are welcome. When adding a new V-World layer, simply add { id, label } to the LAYERS array in src/tools/*.ts to automatically integrate it into the queryOverlays pipeline.