iNavi Maps MCP Server

TypeScript로 구현된 iNavi Maps API 통합 MCP (Model Context Protocol) 서버입니다. Claude Desktop, Cursor 등 MCP 호스트와 stdio 전송 방식으로 통신하여 지오코딩, POI 검색, 경로 탐색 및 지도 시각화 기능을 제공합니다.

주요 기능

• 지오코딩: 주소를 좌표로 변환 및 역지오코딩
• POI 검색: 장소 이름, 주소, 전화번호로 관심 지점 검색
• 경로 계산: 최적 경로 탐색 및 시간 예측
• 지도 시각화: 인터랙티브 지도 생성을 위한 HTML 예제 제공
• 실시간 교통 정보: 경로 계산 시 실시간 교통 상황 반영

빠른 시작

방법 1: .mcpb Bundle (Claude Desktop - 추천)

가장 쉬운 설치 방법입니다. 클릭 몇 번으로 설치 완료!

1. GitHub Releases에서 최신 .mcpb 파일 다운로드
2. 다운로드한 .mcpb 파일을 Claude Desktop에 드래그 앤 드롭 (또는 더블클릭)
3. iNavi Maps API 키 입력 (프롬프트가 나타남)
4. Claude Desktop 재시작

완료! 이제 Claude에게 지도 관련 질문을 할 수 있습니다.

방법 2: npx (모든 MCP 호스트)

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 설정 파일

설정 파일에 다음을 추가:

{
  "mcpServers": {
    "inavi-maps-mcp": {
      "command": "npx",
      "args": ["-y", "inavi-maps-mcp"],
      "env": {
        "INAVI_APPKEY": "your-api-key-here"
      }
    }
  }
}

참고: npx 방식은 Node.js 18+ 설치가 필요합니다.

API 키 발급

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 | 경로 요약 검색 | 출발지, 도착지, 옵션 | 경로 옵션별 요약 정보 | | HTML 예제 도구 | | get_dynamic_map_example | 기본 지도 생성 예제 | - | HTML 코드 (지도 초기화) | | get_marker_map_example | 마커 표시 예제 | - | HTML 코드 (마커 표시) | | get_route_map_example | 경로 표시 예제 | - | HTML 코드 (경로 시각화) | | get_marker_cluster_map_example | 마커 클러스터 예제 | - | HTML 코드 (마커 클러스터링) |

참고:

• API 기반 도구는 구조화된 데이터를 반환합니다
• HTML 예제 도구는 AI가 맞춤형 지도 코드를 생성할 때 사용하는 템플릿입니다
• 상세한 API 레퍼런스는 문서를 참고하세요

사용 예시

위치 검색

"서울 강남구 테헤란로"의 좌표를 알려줘

좌표 (127.027926, 37.497942)의 주소를 알려줘

POI 검색

강남역 근처 스타벅스를 찾아줘

서울 송파구의 병원을 검색해줘

경로 계산

강남역에서 잠실역까지의 경로를 계산해줘

서울시청에서 인천공항까지 오후 3시 출발 기준으로 경로를 알려줘

지도 시각화

지오코딩 결과를 지도에 마커로 표시하는 HTML 페이지를 만들어줘

경로 계산 결과를 지도에 시각화하는 페이지를 만들어줘

여러 POI 검색 결과를 클러스터로 표시하는 지도를 만들어줘

문제 해결

일반적인 문제

MCP 서버가 연결되지 않을 때

1. 빌드 확인 (로컬 개발 시): npm run build 실행
2. 경로 확인: 절대 경로 사용 (상대 경로 불가)
3. 환경 변수 확인: INAVI_APPKEY가 올바르게 설정되었는지 확인
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