카카오 API MCP 서버 만들기 — 지도·메시지·로컬 API 연동 실전 튜토리얼

카카오 로컬·지도·메시지 REST API를 MCP(Model Context Protocol) 서버로 래핑하면 Claude, Cursor 같은 AI 에이전트가 한국어로 “서울 강남역 근처 카페 찾아줘”라고 요청하는 즉시 카카오 API를 직접 호출할 수 있습니다. 이 튜토리얼은 카카오 개발자 앱 등록부터 MCP 서버 코드 작성, Claude Desktop 연결, 동작 확인까지 한 번에 완주합니다. Node.js와 @modelcontextprotocol/sdk만 있으면 별도 프레임워크 없이 구현할 수 있습니다.

왜 카카오 API를 MCP로 연결해야 하나요?

AI 에이전트는 기본적으로 인터넷에 접근하지 못합니다. 장소 검색, 주소 변환, 메시지 전송 같은 실시간 동작이 필요할 때마다 개발자가 API를 직접 호출하고 결과를 붙여넣어야 했습니다. MCP는 이 문제를 해결하는 표준 인터페이스입니다.

사용자 ("강남역 카페 찾아줘")
      ↓
Claude Desktop (MCP 클라이언트)
      ↓  MCP 프로토콜 (stdio / SSE)
카카오 MCP 서버 (우리가 만들 것)
      ↓  HTTPS REST
카카오 로컬 API (REST API 키 인증)
      ↑  JSON 응답
카카오 MCP 서버 → Claude → 사용자

카카오 API는 일 쿼터 내에서 무료로 사용할 수 있고, 한국 주소·POI 데이터 품질이 높아 한국어 AI 에이전트에 최적입니다.

카카오 API 종류와 MCP 활용 범위

API	주요 기능	MCP 적합 여부
카카오 로컬	키워드/카테고리 장소 검색, 지오코딩, 역지오코딩	매우 적합 (REST, JSON)
카카오 메시지	나에게/친구에게 카카오톡 메시지 전송	적합 (OAuth 토큰 필요)
카카오 지도 JS SDK	지도 UI 렌더링	부적합 (브라우저 전용)
카카오 모빌리티	길찾기, 경로 탐색	적합 (REST, 별도 가입)

이 튜토리얼에서는 가장 수요가 높은 카카오 로컬 API(장소 검색·지오코딩)를 중심으로 구현하고, 메시지 API 연동 방법도 추가로 안내합니다.

준비물

Node.js 18 이상 — node -v 로 버전 확인
카카오 개발자 계정 — REST API 키 발급 필요
Claude Desktop (또는 MCP를 지원하는 다른 클라이언트)
터미널 기본 사용 능력

단계별 구현

1단계: 카카오 개발자 앱 등록 및 API 키 발급

카카오 개발자 포털에 로그인합니다.
상단 메뉴에서 내 애플리케이션 → 애플리케이션 추가하기를 클릭합니다.
앱 이름(예: kakao-mcp-server)을 입력하고 저장합니다.
앱 설정 → 앱 키 탭에서 REST API 키를 복사해 둡니다.
플랫폼 탭에서 Web 플랫폼을 추가하고 사이트 도메인을 http://localhost로 등록합니다(로컬 개발용).

REST API 키는 절대 코드에 하드코딩하지 마세요. 환경 변수로 관리합니다.

2단계: Node.js 프로젝트 초기화 및 MCP SDK 설치

mkdir kakao-mcp-server && cd kakao-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk

package.json에 ES 모듈 설정을 추가합니다.

{
  "type": "module",
  "scripts": {
    "start": "node index.js"
  }
}

3단계: 카카오 로컬 API 호출 함수 작성

프로젝트 루트에 kakao.js 파일을 만들어 API 호출 헬퍼를 작성합니다.

// kakao.js
const KAKAO_REST_KEY = process.env.KAKAO_REST_API_KEY;

if (!KAKAO_REST_KEY) {
  throw new Error("KAKAO_REST_API_KEY 환경 변수가 설정되지 않았습니다.");
}

const BASE = "https://dapi.kakao.com/v2/local";

/**
 * 키워드로 장소를 검색합니다.
 * @param {string} query - 검색어
 * @param {number} [page=1] - 페이지 번호 (1~45)
 * @param {number} [size=10] - 결과 수 (1~15)
 */
export async function searchPlaces(query, page = 1, size = 10) {
  const url = new URL(`${BASE}/search/keyword.json`);
  url.searchParams.set("query", query);
  url.searchParams.set("page", String(page));
  url.searchParams.set("size", String(size));

  const res = await fetch(url.toString(), {
    headers: { Authorization: `KakaoAK ${KAKAO_REST_KEY}` },
  });
  if (!res.ok) {
    const err = await res.text();
    throw new Error(`카카오 로컬 API 오류 (${res.status}): ${err}`);
  }
  return res.json();
}

/**
 * 주소를 위경도 좌표로 변환합니다 (지오코딩).
 * @param {string} address - 변환할 주소
 */
export async function geocodeAddress(address) {
  const url = new URL(`${BASE}/search/address.json`);
  url.searchParams.set("query", address);

  const res = await fetch(url.toString(), {
    headers: { Authorization: `KakaoAK ${KAKAO_REST_KEY}` },
  });
  if (!res.ok) {
    const err = await res.text();
    throw new Error(`지오코딩 오류 (${res.status}): ${err}`);
  }
  return res.json();
}

4단계: MCP 도구(Tool) 정의 및 서버 코드 작성

index.js를 작성해 MCP 서버를 구성합니다.

// index.js
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod"; // SDK가 내부적으로 사용; 별도 설치 불필요
import { searchPlaces, geocodeAddress } from "./kakao.js";

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

// 도구 1: 카카오 로컬 키워드 장소 검색
server.tool(
  "kakao_search_places",
  "카카오 로컬 API로 키워드 장소를 검색합니다.",
  {
    query: z.string().describe("검색어 (예: 강남역 카페)"),
    page: z.number().optional().describe("페이지 번호 (기본값: 1)"),
    size: z.number().optional().describe("결과 수 (기본값: 5)"),
  },
  async ({ query, page = 1, size = 5 }) => {
    try {
      const data = await searchPlaces(query, page, size);
      const places = data.documents.map((p) => ({
        이름: p.place_name,
        카테고리: p.category_name,
        주소: p.road_address_name || p.address_name,
        전화: p.phone || "없음",
        URL: p.place_url,
        거리: p.distance ? `${p.distance}m` : "정보 없음",
      }));
      return {
        content: [{ type: "text", text: JSON.stringify(places, null, 2) }],
      };
    } catch (err) {
      return {
        content: [{ type: "text", text: `오류: ${err.message}` }],
        isError: true,
      };
    }
  }
);

// 도구 2: 주소 → 좌표 변환 (지오코딩)
server.tool(
  "kakao_geocode",
  "주소를 위경도 좌표로 변환합니다.",
  {
    address: z.string().describe("변환할 주소 (예: 서울특별시 강남구 테헤란로 152)"),
  },
  async ({ address }) => {
    try {
      const data = await geocodeAddress(address);
      if (!data.documents.length) {
        return {
          content: [{ type: "text", text: "주소를 찾을 수 없습니다." }],
        };
      }
      const result = data.documents[0];
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                주소: result.address_name,
                위도: result.y,
                경도: result.x,
                지번주소: result.address?.address_name,
                도로명주소: result.road_address?.address_name,
              },
              null,
              2
            ),
          },
        ],
      };
    } catch (err) {
      return {
        content: [{ type: "text", text: `오류: ${err.message}` }],
        isError: true,
      };
    }
  }
);

// stdio 트랜스포트 연결 및 서버 시작
const transport = new StdioServerTransport();
await server.connect(transport);

5단계: Claude Desktop 설정 파일에 서버 등록

Claude Desktop의 MCP 설정 파일을 열어 서버를 등록합니다.

macOS 경로: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows 경로: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "kakao": {
      "command": "node",
      "args": ["/절대경로/kakao-mcp-server/index.js"],
      "env": {
        "KAKAO_REST_API_KEY": "여기에_실제_REST_API_키_입력"
      }
    }
  }
}

/절대경로/kakao-mcp-server/index.js 부분을 실제 파일 경로로 바꿔야 합니다. macOS에서는 pwd 명령으로 경로를 확인할 수 있습니다.

6단계: Claude Desktop에서 동작 확인

Claude Desktop을 완전히 종료한 뒤 다시 시작합니다.
채팅창 좌측 하단에 MCP 플러그인 아이콘이 나타나면 등록 성공입니다.
다음과 같이 테스트해 보세요.

“강남역 근처 이탈리안 레스토랑 5곳 알려줘”

정상 동작 시 Claude가 kakao_search_places 도구를 호출하고 실시간 결과를 반환합니다.

카카오 메시지 API 연동 (선택)

카카오 메시지 API는 OAuth 2.0 사용자 토큰이 필요합니다. 서버에서 나에게 메시지 보내기를 구현하려면 아래 흐름을 따릅니다.

1. 카카오 개발자 포털에서 카카오 로그인 활성화
2. 동의 항목에 'talk_message' 범위 추가
3. 인증 코드 발급 → 액세스 토큰 교환
4. 액세스 토큰을 환경 변수로 저장
5. MCP 도구에서 POST /v2/api/talk/memo/default/send 호출

액세스 토큰은 만료 기간이 있어 자동 갱신 로직이 필요하므로, 처음에는 로컬 API부터 완성하는 것을 권장합니다.

흔한 오류와 해결 방법

오류	원인	해결 방법
`401 Unauthorized`	REST API 키 오타 또는 누락	`KAKAO_REST_API_KEY` 환경 변수 재확인
`400 Bad Request`	필수 파라미터 누락	API 요청 URL과 파라미터 확인
`429 Too Many Requests`	일 쿼터 초과	다음 날 재시도 또는 쿼터 상향 신청
MCP 도구가 Claude에 안 보임	설정 파일 경로 오류	`claude_desktop_config.json` 절대 경로 재확인 후 재시작
`Cannot find module`	ES 모듈 설정 누락	`package.json`에 `"type": "module"` 추가

자주 묻는 질문

카카오 REST API 키는 어디서 발급받나요?

카카오 개발자 포털(developers.kakao.com)에 로그인한 뒤 ‘내 애플리케이션 → 앱 설정 → 앱 키’에서 REST API 키를 확인할 수 있습니다. 앱이 없다면 먼저 새 애플리케이션을 등록해야 합니다.

카카오 로컬 API와 지도 API는 무엇이 다른가요?

카카오 로컬 API는 키워드·카테고리 장소 검색, 주소 변환(지오코딩) 등 텍스트 기반 위치 데이터를 반환합니다. 카카오맵 JavaScript API는 지도 UI 렌더링 전용으로 서버 사이드 MCP에는 적합하지 않습니다. MCP 서버에서는 REST로 호출 가능한 카카오 로컬 API를 사용하는 것이 일반적입니다.

카카오 메시지 API를 MCP로 연결하려면 추가 설정이 필요한가요?

네. 카카오 메시지 API(나에게 보내기·친구에게 보내기)는 OAuth 2.0 사용자 인증이 필요합니다. 서버용 REST API 키 외에 액세스 토큰을 별도로 발급받아 환경 변수로 관리해야 합니다.

MCP 서버를 Claude Desktop 외에 다른 클라이언트에도 연결할 수 있나요?

네. MCP는 표준 프로토콜이므로 Cursor, Continue, Zed 등 MCP를 지원하는 모든 클라이언트에서 동일하게 사용할 수 있습니다. 각 클라이언트의 설정 파일 경로와 형식만 다릅니다.

카카오 API 호출 한도(쿼터)가 초과되면 어떻게 되나요?

HTTP 429 또는 오류 코드를 반환합니다. MCP 서버 코드에서 try/catch로 오류를 잡아 사용자에게 안내 메시지를 반환하도록 구현하는 것이 좋습니다. 카카오 개발자 포털에서 일별 쿼터를 확인할 수 있습니다.

완성한 카카오 MCP 서버를 MCP모아에 등록할 수 있나요?

물론입니다. GitHub에 공개 저장소를 만든 뒤 MCP모아 제출 페이지(/submit)를 통해 서버 정보를 등록하면 디렉토리에 노출됩니다.

다음 단계

카카오 MCP 서버를 완성하셨다면 한국어 API를 활용하는 더 많은 MCP 서버도 살펴보세요.

한국어 맞춤법 검사 MCP — 네이버 맞춤법 검사기를 AI 에이전트에 연결
네이웍스 MCP 서버 — LINE WORKS 메시지·캘린더·드라이브를 MCP로 제어
에이전트웹서치 MCP — API 키 없이 네이버·구글 병렬 검색
카카오·네이버 API MCP 전체 목록 — 같은 카테고리의 모든 서버 보기
MCP 서버 전체 디렉토리 — MCP모아가 수집한 모든 한국산 MCP 서버