네이버 지도 MCP 연동 가이드 — Claude에서 장소·경로 검색 자동화하기

Q: MCP 서버를 직접 구현하기 어렵습니다. 다른 방법이 있나요?

MCP 커뮤니티에서 네이버 지도 관련 오픈소스 서버가 공개될 수 있습니다. MCP모아의 지도·위치 카테고리(/category/map-location)를 정기적으로 확인하거나, MCP 서버를 직접 만들어 등록하는 방법도 있습니다.

네이버 지도 API를 MCP 서버로 연결하면 Claude가 자연어 한 문장으로 장소를 검색하고, 주소를 좌표로 변환하며, 경로를 계산할 수 있습니다. 이 가이드는 네이버 클라우드 플랫폼 API 키 발급부터 MCP 서버 구현, Claude Desktop 설정, 실제 동작 확인까지 전 과정을 단계별로 다룹니다. Node.js 기본 지식이 있다면 약 30분 안에 설정을 완료할 수 있습니다.

왜 네이버 지도를 MCP로 연결해야 할까요?

네이버 지도는 국내 장소 검색과 실시간 교통 경로에서 압도적인 데이터를 보유하고 있습니다. 하지만 이를 활용하려면 HTTP 요청 코드를 작성하고, API 문서를 참조해 파라미터를 조합해야 했습니다.

MCP(Model Context Protocol)를 사용하면 달라집니다. Claude 같은 AI 어시스턴트가 MCP 서버를 통해 네이버 지도 API를 직접 호출합니다. “강남역에서 홍대까지 대중교통으로 얼마나 걸려?”라고 물으면 Claude가 스스로 경로 API를 호출해 결과를 해석해줍니다.

아래 표는 MCP 연결 전후 워크플로우 차이를 정리한 것입니다.

항목	MCP 연결 전	MCP 연결 후
장소 검색 방법	직접 HTTP 코드 작성	자연어 프롬프트
API 파라미터 조합	개발자가 직접	Claude가 자동 처리
응답 파싱	코드로 직접 처리	Claude가 해석 후 요약
반복 조회 자동화	별도 스크립트 필요	대화 흐름으로 처리

특히 AI 에이전트가 여러 장소를 순서대로 검색하거나, 검색 결과를 바탕으로 다음 행동을 결정해야 할 때 MCP의 강점이 두드러집니다.

데이터 흐름 이해

설치 전에 전체 구조를 파악하면 디버깅이 훨씬 쉬워집니다.

[Claude Desktop / Claude Code / Cursor]
         │  MCP stdio 통신
         ▼
[네이버 지도 MCP 서버] ── 환경 변수에서 API 키 로드
         │  HTTPS 요청 (Client-ID / Client-Secret 헤더)
         ▼
[네이버 클라우드 플랫폼 Maps API]
  ├── 장소 검색 API  (Local Search)
  ├── 지오코딩 API   (Geocoding)
  ├── 역지오코딩 API (Reverse Geocoding)
  └── Directions API (경로 조회)
         │  JSON 응답
         ▼
[MCP 서버가 결과 파싱 → Claude로 전달]

Claude Desktop이 MCP 서버를 로컬 프로세스로 실행하고, 서버가 네이버 API와 HTTPS로 통신하는 구조입니다. API 키는 환경 변수로만 관리되어 Claude 본체에 직접 노출되지 않습니다.

준비물

항목	버전/링크	비고
Node.js	18 이상	nodejs.org
npm 또는 pnpm	Node.js 설치 시 포함
Claude Desktop	최신 버전	claude.ai/download
네이버 클라우드 플랫폼 계정	—	API 키 발급용, 무료 가입

단계별 설정 방법

1단계: 네이버 클라우드 플랫폼 API 키 발급

console.ncloud.com에 접속해 회원가입하거나 로그인합니다.
상단 메뉴에서 Services → AI·NAVER API → Maps를 선택합니다.
좌측 메뉴 Application 등록을 클릭합니다.
애플리케이션 이름을 입력하고, 사용할 API 항목을 선택합니다.

장소 검색과 경로 조회를 위해 아래 서비스를 체크하세요.
- Geocoding (주소 → 좌표)
- Reverse Geocoding (좌표 → 주소)
- Search (장소 검색)
- Directions 5 또는 Directions 15 (경로 조회)
등록 완료 후 발급된 Client ID와 Client Secret을 복사해 안전한 곳에 보관합니다.

발급된 Client ID와 Client Secret은 API 요청 시 X-NCP-APIGW-API-KEY-ID와 X-NCP-APIGW-API-KEY 헤더로 전달됩니다.

2단계: MCP 서버 프로젝트 초기화

새 디렉터리를 만들고 Node.js 프로젝트를 초기화합니다.

mkdir naver-map-mcp
cd naver-map-mcp
npm init -y
npm install @modelcontextprotocol/sdk node-fetch dotenv

@modelcontextprotocol/sdk는 MCP 서버 구현에 필요한 공식 SDK입니다. node-fetch는 Node.js 18 미만 환경에서 HTTPS 요청에 사용합니다(18 이상이라면 내장 fetch를 그대로 써도 됩니다).

package.json에 타입 설정을 추가합니다.

{
  "type": "module"
}

3단계: 네이버 지도 API 도구 구현

프로젝트 루트에 index.js 파일을 만들고 아래 내용을 작성합니다.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const CLIENT_ID = process.env.NAVER_CLIENT_ID;
const CLIENT_SECRET = process.env.NAVER_CLIENT_SECRET;

const NAVER_HEADERS = {
  "X-NCP-APIGW-API-KEY-ID": CLIENT_ID,
  "X-NCP-APIGW-API-KEY": CLIENT_SECRET,
};

const server = new McpServer({
  name: "naver-map-mcp",
  version: "1.0.0",
});

// 장소 검색 도구
server.tool(
  "search_place",
  "네이버 장소 검색 API로 장소를 검색합니다.",
  {
    query: z.string().describe("검색할 장소 이름 또는 키워드"),
    display: z.number().optional().describe("반환할 결과 수 (기본값: 5)"),
  },
  async ({ query, display = 5 }) => {
    const url = `https://openapi.naver.com/v1/search/local.json?query=${encodeURIComponent(query)}&display=${display}`;
    const res = await fetch(url, {
      headers: {
        "X-Naver-Client-Id": CLIENT_ID,
        "X-Naver-Client-Secret": CLIENT_SECRET,
      },
    });
    const data = await res.json();
    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
    };
  }
);

// 지오코딩 도구 (주소 → 좌표)
server.tool(
  "geocode",
  "주소를 위도·경도 좌표로 변환합니다.",
  {
    address: z.string().describe("변환할 한국 주소"),
  },
  async ({ address }) => {
    const url = `https://naveropenapi.apigw.ntruss.com/map-geocode/v2/geocode?query=${encodeURIComponent(address)}`;
    const res = await fetch(url, { headers: NAVER_HEADERS });
    const data = await res.json();
    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
    };
  }
);

// 역지오코딩 도구 (좌표 → 주소)
server.tool(
  "reverse_geocode",
  "위도·경도 좌표를 주소로 변환합니다.",
  {
    lat: z.number().describe("위도 (예: 37.5665)"),
    lng: z.number().describe("경도 (예: 126.9780)"),
  },
  async ({ lat, lng }) => {
    const url = `https://naveropenapi.apigw.ntruss.com/map-reversegeocode/v2/gc?coords=${lng},${lat}&output=json`;
    const res = await fetch(url, { headers: NAVER_HEADERS });
    const data = await res.json();
    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
    };
  }
);

// 경로 조회 도구
server.tool(
  "get_directions",
  "두 지점 간의 자동차 경로를 조회합니다.",
  {
    startLng: z.number().describe("출발지 경도"),
    startLat: z.number().describe("출발지 위도"),
    goalLng: z.number().describe("목적지 경도"),
    goalLat: z.number().describe("목적지 위도"),
  },
  async ({ startLng, startLat, goalLng, goalLat }) => {
    const url = `https://naveropenapi.apigw.ntruss.com/map-direction/v1/driving?start=${startLng},${startLat}&goal=${goalLng},${goalLat}`;
    const res = await fetch(url, { headers: NAVER_HEADERS });
    const data = await res.json();
    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

이 파일이 MCP 서버의 핵심입니다. 장소 검색에는 네이버 검색 API를, 지오코딩과 경로 조회에는 네이버 클라우드 플랫폼 Maps API를 사용합니다. 두 API는 인증 헤더 형식이 다르니 주의하세요.

참고: 장소 검색(search_place) 도구는 네이버 검색 API를 사용하며, 이 API는 네이버 개발자 센터(developers.naver.com)에서 별도로 발급받은 클라이언트 ID와 시크릿을 사용합니다. 지오코딩과 경로 조회는 네이버 클라우드 플랫폼(console.ncloud.com) 키를 사용합니다. 두 키를 혼동하지 않도록 주의하세요.

4단계: 환경 변수 설정

프로젝트 루트에 .env 파일을 만들고 API 키를 입력합니다.

# 네이버 클라우드 플랫폼 Maps API (지오코딩, 경로)
NAVER_CLIENT_ID=여기에_클라우드_플랫폼_Client_ID_입력
NAVER_CLIENT_SECRET=여기에_클라우드_플랫폼_Client_Secret_입력

.env 파일은 절대 Git에 커밋하지 마세요. 반드시 .gitignore에 추가하세요.

echo ".env" >> .gitignore

5단계: Claude Desktop 설정 파일 편집

Claude Desktop의 MCP 설정 파일 경로는 운영체제별로 다릅니다.

운영체제	설정 파일 경로
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

텍스트 편집기로 설정 파일을 열고 mcpServers 항목에 아래 형식으로 추가합니다.

{
  "mcpServers": {
    "naver-map-mcp": {
      "command": "node",
      "args": ["/절대경로/naver-map-mcp/index.js"],
      "env": {
        "NAVER_CLIENT_ID": "여기에_Client_ID_입력",
        "NAVER_CLIENT_SECRET": "여기에_Client_Secret_입력"
      }
    }
  }
}

/절대경로/naver-map-mcp/ 부분을 실제 프로젝트 경로로 바꾸세요. macOS에서는 ~/ 대신 /Users/사용자명/ 형식의 절대 경로를 사용해야 합니다.

기존에 다른 MCP 서버가 등록돼 있다면 mcpServers 객체 안에 나란히 추가하면 됩니다.

6단계: Claude Desktop 재시작 및 동작 확인

설정 파일을 저장한 뒤 Claude Desktop을 완전히 종료하고 다시 실행합니다. macOS에서는 독(Dock)뿐 아니라 메뉴바 트레이에서도 종료해야 설정이 반영됩니다.

정상 연결됐다면 Claude에게 아래처럼 질문해볼 수 있습니다.

“서울 광화문 주소를 좌표로 변환해줘”
“강남구 삼성동 맛집 검색해줘”
“출발지 위도 37.5665 경도 126.9780, 목적지 위도 37.4979 경도 127.0276 경로 조회해줘”

Claude가 MCP 도구를 호출해 네이버 지도 데이터를 실시간으로 가져오는 것을 확인할 수 있습니다.

흔한 오류와 해결 방법

”Server disconnected” 또는 MCP 서버가 연결되지 않는 경우

설정 파일의 args 경로가 잘못됐거나 node 명령을 찾지 못한 경우에 발생합니다.

# node 실행 경로 확인
which node
# 출력 예: /usr/local/bin/node

확인한 절대 경로를 설정 파일의 "command" 값으로 사용해보세요.

"command": "/usr/local/bin/node"

401 인증 오류가 발생하는 경우

X-NCP-APIGW-API-KEY-ID와 X-NCP-APIGW-API-KEY 헤더에 입력한 키가 맞는지 확인하세요. 특히 네이버 검색 API와 네이버 클라우드 플랫폼 Maps API는 키가 다르므로 혼동하지 않도록 주의합니다. 콘솔에서 해당 API 서비스가 활성화되어 있는지도 확인하세요.

”Cannot find package” 오류

cd /절대경로/naver-map-mcp
npm install

프로젝트 디렉터리에서 의존성을 다시 설치하고 Claude Desktop을 재시작하세요.

Claude Desktop 설정 파일 JSON 오류

설정 파일은 순수 JSON 형식이라 쉼표 하나, 중괄호 하나가 어긋나도 서버 전체가 실행되지 않습니다. JSONLint 같은 온라인 도구에 설정 내용을 붙여넣어 유효성을 검사해보세요.

API 응답이 오지만 결과가 비어있는 경우

네이버 클라우드 플랫폼 콘솔에서 해당 API의 일일 사용량 한도를 초과하지 않았는지 확인하세요. 무료 크레딧 소진 시 유료 전환이 필요합니다. console.ncloud.com의 사용량 모니터링 페이지에서 잔여량을 확인할 수 있습니다.

활용 시나리오

네이버 지도 MCP를 연결하면 아래와 같은 작업을 AI 에이전트로 자동화할 수 있습니다.

시나리오	사용 도구	예시 프롬프트
고객 주소 일괄 좌표 변환	geocode	”이 CSV의 주소들을 좌표로 변환해줘”
주변 맛집 추천	search_place	”현재 위치 근처 일식당 추천해줘”
배송 경로 최적화	get_directions	”이 5곳을 순서대로 방문하는 경로 알려줘”
주소 정규화	reverse_geocode	”이 좌표들의 법정동 주소로 변환해줘”

특히 여러 도구를 연속으로 호출하는 멀티스텝 에이전트 워크플로우에서 효과적입니다.

자주 묻는 질문

네이버 지도 API는 무료로 사용할 수 있나요?

네이버 클라우드 플랫폼 Maps API는 월 일정량까지 무료 크레딧이 제공됩니다. 지오코딩·장소 검색 등 API별로 무료 한도가 다르므로 console.ncloud.com의 요금 안내를 확인하세요.

Claude Desktop 외에 Cursor나 Claude Code에서도 사용할 수 있나요?

네. MCP 프로토콜을 지원하는 Cursor, Claude Code, Zed 등 어느 클라이언트에서도 동일한 mcpServers 설정 방식으로 연결할 수 있습니다. 각 클라이언트의 설정 파일 위치만 다를 뿐 구조는 동일합니다.

네이버 지도 MCP로 실시간 교통 정보도 조회할 수 있나요?

네이버 클라우드 플랫폼 Directions API를 구현에 포함하면 실시간 교통 상황을 반영한 경로 조회가 가능합니다. 다만 실시간 교통 정보는 별도 API 엔드포인트를 사용하며 요금이 발생할 수 있으니 공식 문서를 확인하세요.

네이버 지도 API 키가 유출되면 어떻게 해야 하나요?

즉시 console.ncloud.com에 로그인해 해당 애플리케이션의 시크릿 키를 재발급하세요. 이전 키는 즉시 무효화됩니다. API 키는 절대 GitHub 등 공개 저장소에 올리지 말고, .env 파일은 .gitignore에 반드시 포함하세요.

MCP 서버를 직접 구현하기 어렵습니다. 다른 방법이 있나요?

MCP 커뮤니티에서 네이버 지도 관련 오픈소스 서버가 공개될 수 있습니다. 지도·위치 카테고리를 정기적으로 확인하거나, 직접 만든 서버를 MCP모아에 등록해 커뮤니티와 공유하는 방법도 있습니다.

네이버 지도 API와 카카오맵 API 중 어느 것이 MCP에 더 적합한가요?

두 서비스 모두 MCP 서버로 구현할 수 있습니다. 네이버 지도는 국내 장소 검색 데이터가 풍부하고, 카카오맵은 로컬 비즈니스 데이터와 도보 경로에 강점이 있습니다. 사용 목적에 따라 선택하거나 두 서버를 함께 등록해 Claude가 상황에 맞게 활용하도록 구성할 수도 있습니다.

다음 단계

네이버 지도 MCP 설정을 마쳤다면 활용 범위를 더 넓혀보세요.

지도·위치 카테고리 탐색: 지도·위치 카테고리에서 국내 지도 API를 다루는 더 많은 MCP 서버를 찾아볼 수 있습니다.
전체 MCP 서버 목록 보기: MCP모아 서버 목록에서 다양한 국내외 MCP 서버를 검색하세요.
직접 만든 MCP 서버 등록: 이 가이드를 참고해 만든 네이버 지도 MCP 서버나 다른 한국 API MCP 서버를 MCP모아에 등록해 커뮤니티와 공유해보세요.
다른 가이드 보기: 가이드 목록에서 다른 MCP 서버 연동 가이드를 확인하세요.

네이버 지도 API를 MCP로 연결하면 위치 데이터를 다루는 워크플로우가 근본적으로 달라집니다. 복잡한 API 코드를 작성하지 않고도 Claude가 장소를 검색하고, 경로를 계산하며, 주소를 변환할 수 있습니다. 오늘 설정을 마쳤다면 일상적으로 사용하는 지도 관련 작업을 Claude에게 직접 맡겨보세요.