kakaomap-mcp-server by devstefancho-inara - MCP Server

Kakao Map MCP Server

카카오맵 장소 검색 API를 사용하는 MCP (Model Context Protocol) 서버입니다. Claude Desktop 또는 다른 MCP 클라이언트에서 카카오맵의 장소 검색 기능을 사용할 수 있습니다.

기능

장소 검색: 키워드로 장소를 검색하고 상세 정보를 가져옵니다
좌표 기반 검색: 특정 좌표 주변의 장소를 검색합니다
반경 검색: 지정된 반경 내의 장소를 검색합니다
정렬 옵션: 정확도순 또는 거리순으로 결과를 정렬합니다

사전 준비

1. Python 설치

Python 3.10 이상이 필요합니다. 설치 확인:

python --version

2. Kakao REST API 키 발급

Kakao Developers 에 접속하여 로그인합니다
우측 상단의 "내 애플리케이션" 메뉴를 클릭합니다
"애플리케이션 추가하기" 버튼을 클릭합니다
앱 이름과 사업자명을 입력하고 저장합니다
생성된 앱을 클릭하여 "앱 키" 섹션으로 이동합니다
"REST API 키"를 복사합니다

플랫폼 설정 (선택사항)

2024년 12월 1일부터 신규 앱이 카카오맵 API를 호출하려면 플랫폼 설정이 필요합니다:

앱 설정 페이지에서 "플랫폼" 메뉴로 이동
"Web 플랫폼 등록" 클릭
사이트 도메인 입력 (로컬 테스트: http://localhost)

자세한 내용은 Kakao Developers 문서를 참조하세요.

설치 방법

방법 1: uvx 사용 (권장)

uvx를 사용하면 별도의 설치 없이 GitHub에서 직접 실행할 수 있습니다.

uv 설치 (처음 한 번만)

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Claude Desktop 설정

claude_desktop_config.json 파일을 열어 다음 설정을 추가합니다:

macOS/Linux:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

code %AppData%\Claude\claude_desktop_config.json

설정 내용:

{
  "mcpServers": {
    "kakaomap": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/yourusername/kakaomap-mcp-creator.git@v0.1.0",
        "kakaomap-server"
      ],
      "env": {
        "KAKAO_REST_API_KEY": "your_kakao_rest_api_key_here"
      }
    }
  }
}

중요:

yourusername을 실제 GitHub 사용자명으로 변경하세요
your_kakao_rest_api_key_here를 실제 Kakao REST API 키로 변경하세요
최신 버전을 사용하려면 @v0.1.0 부분을 제거하세요

방법 2: 로컬 개발 설치

프로젝트를 수정하거나 개발하려면 로컬에 설치합니다.

1. 프로젝트 클론

git clone <repository-url>
cd kakaomap-mcp-creator

2. 가상 환경 생성 및 활성화

uv 사용 (권장):

# 가상 환경 생성 및 활성화
uv venv
source .venv/bin/activate  # macOS/Linux
# 또는
.venv\Scripts\activate  # Windows

Python venv 사용:

python -m venv .venv
source .venv/bin/activate  # macOS/Linux
# 또는
.venv\Scripts\activate  # Windows

3. 의존성 설치

# uv 사용
uv pip install -e .

# pip 사용
pip install -e .

4. 환경 변수 설정

.env 파일을 생성하고 Kakao REST API 키를 설정합니다:

cp .env.example .env

.env 파일을 편집하여 실제 API 키를 입력합니다:

KAKAO_REST_API_KEY=your_actual_api_key_here

서버 테스트

서버가 정상적으로 작동하는지 테스트:

# 로컬 개발 설치의 경우
uv run python src/kakaomap_server/kakaomap_server.py

# 또는 직접 실행
python src/kakaomap_server/kakaomap_server.py

서버가 시작되면 로그가 출력됩니다. Ctrl+C로 종료할 수 있습니다.

Claude Desktop 연동 (로컬 개발 설치의 경우)

로컬 개발 설치를 한 경우, 다음과 같이 Claude Desktop에 연동할 수 있습니다.

1. Claude Desktop 설치

Claude Desktop을 다운로드하여 설치하고 최신 버전으로 업데이트합니다.

2. 설정 파일 편집

Claude Desktop 설정 파일을 엽니다:

macOS/Linux:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

code %AppData%\Claude\claude_desktop_config.json

3. MCP 서버 설정 추가

uv 사용 (권장)

macOS/Linux:

{
  "mcpServers": {
    "kakaomap": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/kakaomap-mcp-creator",
        "run",
        "kakaomap-server"
      ],
      "env": {
        "KAKAO_REST_API_KEY": "your_kakao_rest_api_key"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "kakaomap": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\ABSOLUTE\\PATH\\TO\\kakaomap-mcp-creator",
        "run",
        "kakaomap-server"
      ],
      "env": {
        "KAKAO_REST_API_KEY": "your_kakao_rest_api_key"
      }
    }
  }
}

Python 직접 사용

macOS/Linux:

{
  "mcpServers": {
    "kakaomap": {
      "command": "/ABSOLUTE/PATH/TO/.venv/bin/python",
      "args": [
        "/ABSOLUTE/PATH/TO/kakaomap-mcp-creator/src/kakaomap_server/kakaomap_server.py"
      ],
      "env": {
        "KAKAO_REST_API_KEY": "your_kakao_rest_api_key"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "kakaomap": {
      "command": "C:\\ABSOLUTE\\PATH\\TO\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\ABSOLUTE\\PATH\\TO\\kakaomap-mcp-creator\\src\\kakaomap_server\\kakaomap_server.py"
      ],
      "env": {
        "KAKAO_REST_API_KEY": "your_kakao_rest_api_key"
      }
    }
  }
}

주의사항:

/ABSOLUTE/PATH/TO/kakaomap-mcp-creator를 실제 프로젝트의 절대 경로로 변경하세요
your_kakao_rest_api_key를 실제 Kakao REST API 키로 변경하세요
Windows에서는 경로에 \\ (이중 백슬래시) 또는 /를 사용하세요

경로 확인 방법:

# macOS/Linux
pwd

# Windows (Command Prompt)
cd

4. Claude Desktop 재시작

설정을 저장한 후 Claude Desktop을 완전히 종료하고 다시 시작합니다:

macOS: Cmd+Q 또는 메뉴에서 "Quit Claude" 선택
Windows: 시스템 트레이에서 Claude 아이콘 우클릭 후 "Quit" 또는 "Exit" 선택

단순히 창을 닫는 것만으로는 설정이 적용되지 않습니다.

사용 방법

Claude Desktop을 재시작한 후, 채팅 창 하단의 "Search and tools" 아이콘을 클릭하여 search_place 도구가 표시되는지 확인합니다.

사용 예시

기본 검색

서울역 근처 카페를 찾아줘

강남역 맛집 추천해줘

좌표 기반 검색

좌표 (37.5665, 126.9780) 주변 500m 이내의 약국을 찾아줘

페이징

홍대 술집을 찾아줘. 결과가 많으면 다음 페이지도 보여줘

Tool 파라미터

search_place 도구는 다음 파라미터를 지원합니다:

query (필수): 검색 키워드
x (선택): 중심 좌표의 경도 (longitude)
y (선택): 중심 좌표의 위도 (latitude)
radius (선택): 검색 반경 (미터), 0-20000 (x, y와 함께 사용)
page (선택): 페이지 번호, 1-45 (기본값: 1)
size (선택): 페이지당 결과 수, 1-15 (기본값: 15)
sort (선택): 정렬 방식, "accuracy" 또는 "distance" (기본값: "accuracy")

트러블슈팅

MCP 서버가 Claude Desktop에 표시되지 않음

claude_desktop_config.json 파일의 JSON 문법이 올바른지 확인
경로가 절대 경로인지 확인
Claude Desktop을 완전히 종료하고 재시작 (Cmd+Q 또는 Quit)

로그 파일 확인:

# macOS
tail -f ~/Library/Logs/Claude/mcp*.log

API 키 오류

.env 파일에 KAKAO_REST_API_KEY가 올바르게 설정되었는지 확인
claude_desktop_config.json의 env 섹션에 API 키가 올바르게 설정되었는지 확인
Kakao Developers 콘솔에서 API 키가 활성화되어 있는지 확인

검색 결과가 없음

검색 키워드가 너무 구체적이지 않은지 확인
좌표와 반경을 사용하는 경우, 범위를 넓혀서 다시 시도
Kakao Map API의 사용 한도를 초과하지 않았는지 확인

HTTP 429 (Too Many Requests) 오류

Kakao API의 호출 한도를 초과했습니다. 잠시 기다린 후 다시 시도하세요.

API 제한사항

하루 호출 한도: Kakao Developers 콘솔에서 확인
검색 결과: 최대 45페이지 (페이지당 최대 15개)
반경 검색: 최대 20km

자세한 내용은 Kakao Local API 문서를 참조하세요.

라이선스

MIT License

기여

이슈와 풀 리퀘스트를 환영합니다!

devstefancho-inara/kakaomap-mcp-server