MCP Server for iNavi Maps API - Geocoding, POI Search, Route Planning for Claude AI
npm install @inavi-maps/mcp-serverTypeScript로 구현된 iNavi Maps API 통합 MCP (Model Context Protocol) 서버입니다.
Claude Desktop, Cursor 등 MCP 호스트와 stdio 전송 방식으로 통신하여 지오코딩, POI 검색, 경로 탐색 및 지도 시각화 기능을 제공합니다.
- 지오코딩: 주소를 좌표로 변환 및 역지오코딩
- POI 검색: 장소 이름, 주소, 전화번호로 관심 지점 검색
- 경로 계산: 최적 경로 탐색 및 시간 예측
- 지도 시각화: 인터랙티브 지도 생성을 위한 HTML 예제 제공
- 실시간 교통 정보: 경로 계산 시 실시간 교통 상황 반영
가장 쉬운 설치 방법입니다. 클릭 몇 번으로 설치 완료!
1. GitHub Releases에서 최신 .mcpb 파일 다운로드
2. 다운로드한 .mcpb 파일을 Claude Desktop에 드래그 앤 드롭 (또는 더블클릭)
3. iNavi Maps API 키 입력 (프롬프트가 나타남)
4. Claude Desktop 재시작
완료! 이제 Claude에게 지도 관련 질문을 할 수 있습니다.
Cursor, Windsurf, Continue, Cline 등 다른 MCP 호스트를 사용하는 경우:
Claude Desktop:
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Cursor/Windsurf/Continue/Cline:
- 각 에디터의 MCP 설정 파일
설정 파일에 다음을 추가:
``json`
{
"mcpServers": {
"inavi-maps-mcp": {
"command": "npx",
"args": ["-y", "inavi-maps-mcp"],
"env": {
"INAVI_APPKEY": "your-api-key-here"
}
}
}
}
> 참고: npx 방식은 Node.js 18+ 설치가 필요합니다.
iNavi Maps API를 사용하려면 API 키가 필요합니다:
1. iNavi Maps API 방문
2. 회원가입 또는 로그인
3. 대시보드에서 API 키 생성
4. 생성된 API 키를 복사하여 사용
---
| 도구 이름 | 설명 | 주요 입력 | 주요 출력 |
|-----------|------|-----------|-----------|
| API 기반 도구 |
| geocoding | 주소/장소명을 좌표로 변환 | query (주소) | 좌표, 주소 정보 |reverse_geocoding
| | 좌표를 주소로 변환 | posx, posy (좌표) | 주소 정보 |searches
| | POI 통합 검색 | query (키워드) | POI 목록 (좌표, 주소, 전화번호 등) |route_time
| | 경로 시간 예측 검색 | 출발지, 도착지, 시간 | 상세 경로 안내 (거리, 시간, 요금) |route_summary
| | 경로 요약 검색 | 출발지, 도착지, 옵션 | 경로 옵션별 요약 정보 |list_map_examples
| HTML 예제 도구 |
| | 지도 예제 목록 조회 | category (선택) | 사용 가능한 예제 목록 (메타데이터) |get_map_example
| | 특정 지도 예제 조회 | id (필수) | HTML 코드 (지도 시각화 템플릿) |
참고:
- API 기반 도구는 구조화된 데이터를 반환합니다
- HTML 예제 도구는 AI가 맞춤형 지도 코드를 생성할 때 사용하는 템플릿입니다
- 상세한 API 레퍼런스는 문서를 참고하세요
---
`
"서울 강남구 테헤란로"의 좌표를 알려줘
`
좌표 (127.027926, 37.497942)의 주소를 알려줘
`
강남역 근처 스타벅스를 찾아줘
`
서울 송파구의 병원을 검색해줘
`
강남역에서 잠실역까지의 경로를 계산해줘
`
서울시청에서 인천공항까지 오후 3시 출발 기준으로 경로를 알려줘
`
지오코딩 결과를 지도에 마커로 표시하는 HTML 페이지를 만들어줘
`
경로 계산 결과를 지도에 시각화하는 페이지를 만들어줘
`
여러 POI 검색 결과를 클러스터로 표시하는 지도를 만들어줘
---
#### MCP 서버가 연결되지 않을 때
1. 빌드 확인 (로컬 개발 시): npm run build 실행INAVI_APPKEY
2. 경로 확인: 절대 경로 사용 (상대 경로 불가)
3. 환경 변수 확인: 가 올바르게 설정되었는지 확인
4. MCP Host 재시작: 설정 변경 후 반드시 재시작
#### API 키 관련 문제
`
Invalid environment variables: { INAVI_APPKEY: { _errors: [ 'Required' ] } }
해결 방법:
- MCP 설정 파일의 INAVI_APPKEY에 올바른 API 키 입력
- API 키에 공백이나 따옴표가 없는지 확인
- MCP Host 재시작
#### JSON 파싱 에러
`
Unexpected token...is not valid JSON
해결 방법:
- 최신 버전 사용 (이미 수정됨)
- 코드에 console.log` 대신 MCP Logging 사용
더 자세한 문제 해결 방법은 Troubleshooting Guide를 참고하세요.
---
- Claude Desktop 설정 가이드
- Cursor 설정 가이드
- 로컬 개발 가이드
- API 레퍼런스 - 모든 도구의 상세 문서
- 개발자 가이드 (CLAUDE.md) - 프로젝트 구조, 아키텍처, 코드 컨벤션
- Troubleshooting Guide - 상세한 문제 해결 가이드
---
MIT License - 자유롭게 사용, 수정, 배포할 수 있습니다. 자세한 내용은 LICENSE 파일을 참조하세요.
---
- Model Context Protocol 문서
- Claude Desktop
- iNavi Maps API 문서
- GitHub Repository