Skip to main content
Glama

🇰🇷 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)

Tool

Description

resolve_parcel

Address/Lot Number/PNU → Standardized PNU, land category, officially assessed land price, administrative district, WGS84 coordinates

get_zoning

Zoning (Urban/Management/Agriculture/Nature) + Land Use Districts (8 types) + Land Use Zones (Development Restriction/Urban Natural Park) + Land Transaction Permit Zones

get_district_plan

District Unit Planning Zones + Development Activity Permit Restriction Zones

get_urban_facility

9 types of urban planning facilities (Road/Transport/Space/Distribution/Public Culture/Disaster/Health/Environment/Other). Distinguishes between "encroachment" vs "adjacency" via radius_m parameter

get_other_law_designations

42 other legal designation layers (Farmland, Forestry, Industrial Complex, Water Quality, Livestock, Cultural Heritage, Natural Park, Special Districts, Housing Improvement, Disaster, Marine, Aviation). Automatically flags candidates for Article 76(5) priority delegation

get_land_attributes

Land category (28 types) parsing + individual officially assessed land price + building information

analyze_parcel

Parallel execution of the 6 tools above + generation of hints for the next step in korean-law-mcp

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.

Available Tools

8 tools
analyze_parcelA

One-shot comprehensive analysis — chains all the above tools and returns a single integrated record: parcel + zoning + district_plan + urban_facility + other_law_designations + priority_delegation_hint + buildings + next_steps. Use this when you want a complete 토지이용계획확인서-equivalent JSON in one call. next_steps tells you exactly which korean-law MCP queries to run afterward.

Inputs: query (required).

discover_toolsA

List all currently wired tools in this MCP build.

Inputs: no named parameters.

get_district_planA

Return 지구단위계획구역 membership and 개발행위허가제한지역 overlays. When district_plan is non-empty, 건폐율·용적률·용도 may be overridden by the plan (see 국토계획법 제52조). V-World only returns the geometric hit — actual plan text must come from 지자체 고시문.

Inputs: query (required).

get_land_attributesA

Return detailed parcel attributes: parsed 지목 (28-type mapping), 지번 components, 공시지가, administrative breakdown, and 건축물 presence at the point. Note: 면적(land area) is NOT provided — V-World doesn't expose 토지대장 area field.

Inputs: query (required).

get_other_law_designationsA

Return '다른 법령에 따른 지정사항' overlays — ~38 layers across 농지/산림/산업단지/수질·환경/축산/문화재/자연공원/특수지구/주거정비/재해/해양/항공. Each hit includes governing_law and a triggers_priority_delegation flag. When any flag is true, 국토계획법 제76조⑤ priority delegation applies and the governing_law's 행위제한 overrides the 국토계획법 시행령 별표 — look up those provisions via korean-law MCP first.

Inputs: query (required).

get_urban_facilityA

Return 도시계획시설 overlaps: 도로, 교통시설, 공간시설(공원·녹지), 유통공급, 공공문화체육, 방재, 보건위생, 환경기초, 기타기반시설. Overlap with 도시계획시설 triggers 건축제한 (국계법 제64조) or 미집행 저촉 리스크. Exact 저촉 면적 needs geometric intersection, not returned here.

Inputs: query (required), radius_m.

get_zoningA

Return 용도지역 (도시/관리/농림/자연환경보전 + subclass), 용도지구 (경관/고도/방화/방재/보호/취락/개발진흥/특정용도제한), 용도구역 (개발제한/도시자연공원), and 토지거래허가구역 overlays. Empty array = no overlay at this point (not an error). Use the zone name with korean-law MCP to get 건폐율·용적률.

Inputs: query (required).

resolve_parcelA

Resolve address or PNU → canonical parcel: PNU, 지번, parsed 지목 (e.g. 공장용지), refined address, WGS84 coordinates, 공시지가, administrative hierarchy. Foundation for all other tools.

Inputs: query (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: resolve_parcel for resolution, get_land_attributes for parcel details, get_zoning for zoning overlays, get_district_plan for district plans, get_urban_facility for facilities, get_other_law_designations for other laws, analyze_parcel as a composite, and discover_tools for listing. No two tools overlap in functionality.

    Naming Consistency4/5

    Most tools follow a 'get_X' pattern, but three use different verbs: analyze_parcel, discover_tools, resolve_parcel. The structure is still clear and predictable, and all names use snake_case, so the inconsistency is minor.

    Tool Count5/5

    With 8 tools, the server covers essential land information queries and includes a composite tool for one-shot analysis. This is well-scoped; each tool earns its place without being overwhelming or sparse.

    Completeness4/5

    The tool set covers parcel resolution, attributes, zoning, district plans, urban facilities, other law designations, and a composite with buildings. Minor gaps exist (no separate building tool, no area field), but the composite mitigates these and the domain is well-covered.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables real-time search and analysis of Korean laws, legal precedents, and administrative rules through the National Law Information Center Open API, allowing AI agents to access official legal information for contract review, compliance, and legal research.
      75
      -
    • A
      license
      A
      quality
      D
      maintenance
      Provides 12 tools to query South Korean building register data, including title sheets, floor details, and official house prices via the data.go.kr API. It enables users to perform smart building lookups and region code searches using natural language.
      12
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to search, retrieve, and analyze South Korean legal documents including statutes, precedents, constitutional decisions, and administrative rulings via the Ministry of Government Legislation Open API. Provides 89 specialized tools with features like legal abbreviation auto-recognition, annex extraction, and complex research chain workflows.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables natural language access to 11 Korean building data tools including building registers, permits, comprehensive profiles with zoning, floor composition, district statistics, old building analysis, price history, demolitions, and permit pipeline.
      76
      MIT