Content
# vworld-api-mcp
> Ministry of Land, Infrastructure and Transport v-world Spatial Information OpenAPI MCP Server
v-world spatial information open platform's OpenAPI exposed through [Model Context Protocol](https://modelcontextprotocol.io), allowing Claude Desktop, Claude Code, and other MCP compatible clients to query and analyze Korean spatial information in natural language.
## Features
- 🌐 **177 WFS layers** integrated into a single tool (`vworld_query_features`)
- 🔍 Geocoding (address↔coordinates) and integrated search (place·address·administrative district·road) supported
- 🏠 Real estate analysis (official land price·actual transaction price·building ledger·land use plan) supported
- 🗺️ **NED 12/12 full coverage** — individual·collective housing prices, land characteristics/shape/forest, building title·number·use supported
- ⚙️ 4 profiles (`lite`/`standard`/`full`/`realestate`) for token efficiency adjustment
## Installation
```bash
npm install -g vworld-api-mcp
```
or clone directly:
```bash
git clone <repo> && cd vworld-api-mcp
npm install
npm run build
```
## v-world API Key Issuance
1. https://www.vworld.kr → Sign up → Log in
2. Developer Center → Authentication key issuance (domain is `localhost` or personal domain registration)
3. Set the issued key in environment variables
## Environment Variables (`.env.local`)
```bash
# Required
VWORLD_API_KEY=issued_36_character_UUID
VWORLD_DOMAIN=localhost
# Optional
MCP_PROFILE=standard # lite | standard | full | realestate
VWORLD_CACHE_TTL=3600
LOG_LEVEL=info
```
## Claude Desktop Integration
`~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"vworld": {
"command": "node",
"args": ["/path/to/vworld-api-mcp/dist/index.js"],
"env": {
"VWORLD_API_KEY": "...",
"VWORLD_DOMAIN": "localhost",
"MCP_PROFILE": "standard"
}
}
}
}
```
## Tool List (v0.3)
### Layer 1 — Always Loaded (8)
| Tool | Purpose |
|---|---|
| `vworld_geocode` | Address→coordinates |
| `vworld_reverse_geocode` | Coordinates→address |
| `vworld_search` | Integrated search (PLACE/ADDRESS/DISTRICT/ROAD) |
| `vworld_list_layers` | 177 WFS layer catalog search |
| `vworld_describe_layer` | Layer schema inquiry |
| `vworld_query_features` | WFS·2D Data integrated inquiry (177 layers → 1 tool) |
| `vworld_get_static_map_url` | StaticMap PNG map URL generation (center+zoom) |
| `vworld_get_wms_url` | WMS PNG map URL generation (area bbox specification) |
### Layer 2 — NED National Focus Data (12, v0.2 — 12/12 full coverage)
| Tool | Purpose |
|---|---|
| `vworld_get_land_price` | Individual official land price inquiry |
| `vworld_get_house_price` | Individual housing price inquiry |
| `vworld_get_apartment_price` | Collective housing price inquiry |
| `vworld_get_real_estate_trade` | Real estate actual transaction price inquiry |
| `vworld_get_land_characteristics` | Land characteristic information inquiry |
| `vworld_get_land_use_plan` | Land use plan inquiry |
| `vworld_get_building_use` | Building use information inquiry |
| `vworld_get_building_ledger` | Building ledger inquiry |
| `vworld_get_building_ho` | Building number inquiry |
| `vworld_get_building_title` | Building title inquiry |
| `vworld_get_land_forest_info` | Land·forest information inquiry |
| `vworld_get_land_shape_info` | Land shape information inquiry |
## Usage Examples
### Natural Language Question → MCP Tool Invocation
```
User: "Tell me the coordinates of 19, Duhom-ro 5-gil, Sejong-si"
→ vworld_geocode(address="19, Duhom-ro 5-gil, Sejong-si", type="ROAD")
→ {x: 127.2587, y: 36.5037, ...}
```
```
User: "Give me the administrative boundary GeoJSON of Gangnam-gu"
→ vworld_list_layers(keyword="administrative") // candidate discovery
→ vworld_query_features(layer="lt_c_adsigg", attr_filter="sig_kor_nm:LIKE:Gangnam%")
→ GeoJSON FeatureCollection
```
## Profiles
| Profile | Number of Tools | Purpose |
|---|---|---|
| `standard` (default) | 8 always + 12 defer | Balanced |
| `full` | 20 all always | All tools immediately exposed |
| `realestate` | 8 + 4 NED always | Real estate analysis specialized |
| `lite` | (not implemented) | lofin style catalog pattern |
## Development
```bash
npm install
cp .env.local.example .env.local # key input
npm test # unit tests
npm run test:integration # actual API call (key required)
npm run dev # development server execution
npm run build # build
```
## License
MIT
