内容
-api-mcp
> 국토교통부 v-world 공간정보 OpenAPI MCP 서버
v-world 공간정보 오픈플랫폼의 OpenAPI를 [Model Context Protocol](https://modelcontextprotocol.io)로 노출해, Claude Desktop·Claude Code·기타 MCP 호환 클라이언트가 자연어로 한국 공간정보를 조회·분석할 수 있게## 특징
- 🌐개 WFS 레이어** 도구(`vworld_query_features 통합
- 🔍 지오코딩(주소↔좌표 검색(장소·주소·행정구역·도로) 지원
🏠 부동산 분석(공시지가·실거래가·건축물·토지이용계획)- 🗺️ **12/12 전체 커버리지** — 개별·공동주택가격지특성/형상/임야, 건축물 표제부수·용도 지원
- ⚙️ 4가지 프로lite`/`standard`/`full`/`realestate`)로 토큰 효율 조정
## 설치
```bash
npm install -g vworldcp
```
또는 직접 clone:
```bash
git clone <repo> && cd vworld-api-mcp
npm install
npm run build
```
## v-world API 키 발급
1. https://www.vworld.kr → 회원가입 → 로그인
2. 개발자센터 → 인증키 발급 (도메인은 `localhost` 또는 본인 도메인 등록)
3. 발급된 키를 환경변수에 설정
## 环境变量 (`.env.local`)
```bash
# 필수
VWORLD_API_KEY=발급받은_36자_UUID
VWORLD_DOMAIN=localhost
# 选择
MCP_PROFILE=standard # lite | standard | full | realestate
VWORLD_CACHE_TTL=3600
LOG_LEVEL=info
```
## Claude Desktop 연동
`~/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"
}
}
}
}
```
## 工具列表
### Layer 1 — 总是加载 (8个)
| 工具 | 用途 |
|---|---|
| `vworld_geocode` | 地址→坐标 |
| `vworld_reverse_geocode` | 坐标→地址 |
| `vworld_search` | 综合搜索(地点/地址/行政区/道路) |
| `vworld_list_layers` | 177个WFS层目录搜索 |
| `vworld_describe_layer` | 层模式查询 |
| `vworld_query_features` | WFS·2D数据综合查询 (177层 → 1工具) |
| `vworld_get_static_map_url` | StaticMap PNG地图URL生成 (中心+缩放) |
| `vworld_get_wms_url` | WMS PNG地图URL生成 (区域bbox指定) |
### Layer 2 — NED国家重点数据 (12个, v0.2 — 12/12全覆盖)
| 工具 | 用途 |
|---|---|
| `vworld_get_land_price` | 单个公示地价查询 |
| `vworld_get_house_price` | 单个住宅价格查询 |
| `vworld_get_apartment_price` | 公共住宅价格查询 |
| `vworld_get_real_estate_trade` | 房地产实际交易价格查询 |
| `vworld_get_land_characteristics` | 土地特性信息查询 |
| `vworld_get_land_use_plan` | 土地利用计划查询 |
| `vworld_get_building_use` | 用途建筑信息查询 |
| `vworld_get_building_ledger` | 建筑物台账查询 |
| `vworld_get_building_ho` | 建筑物单元查询 |
| `vworld_get_building_title` | 建筑物标题查询 |
| `vworld_get_land_forest_info` | 土地·林地信息查询 |
| `vworld_get_land_shape_info` | 土地形状信息查询 |
## 使用示例
### 自然语言问题 → MCP工具调用
```
用户: "세종시 도움5로 19 坐标 알려줘"
→ vworld_geocode(address="세종시 도움5로 19", type="ROAD")
→ {x: 127.2587, y: 36.5037, ...}
```
```
用户: "강남구 行政边界 GeoJSON 给我"
→ vworld_list_layers(keyword="行政") // 候选发现
→ vworld_query_features(layer="lt_c_adsigg", attr_filter="sig_kor_nm:LIKE:강남%")
→ GeoJSON FeatureCollection
```
## 配置文件
| 配置文件 | 工具数量 | 用途 |
|---|---|---|
| `standard` (默认) | 8 always + 12 defer | 平衡型 |
| `full` | 20个全部always | 所有工具立即暴露 |
| `realestate` | 8 + 4 NED always | 房地产分析专用 |
| `lite` | (未实现) | lofin风格目录模式 |
## 开发
```bash
npm install
cp .env.local.example .env.local # 填写密钥
npm test # 单元测试
npm run test:integration # 实际API调用 (需要密钥)
npm run dev # 开发服务器运行
npm
