@itapi-core/mcp-kakao

MCP server for KakaoTalk personal & business messaging.

Tools

인증 (Authentication)

| Tool | Description | |------|-------------| | kakao_auth_get_authorization_url | OAuth2 인증 URL 생성 | | kakao_auth_exchange_code | 인가 코드 → 액세스 토큰 교환 | | kakao_auth_refresh_token | 액세스 토큰 갱신 | | kakao_auth_get_token_info | 토큰 유효성 확인 | | kakao_auth_get_user_info | 로그인 사용자 정보 조회 | | kakao_auth_update_profile | 사용자 프로필 업데이트 | | kakao_auth_logout | 로그아웃 (단일/전체 기기) | | kakao_auth_status | 현재 인증 상태 확인 |

개인 메시지 (Personal Messaging)

| Tool | Description | |------|-------------| | kakao_get_friends | 친구 목록 조회 | | kakao_get_channel_relations | 채널 관계 조회 | | kakao_add_channel | 채널 추가(친구 추가) | | kakao_send_memo_text | 나에게 텍스트 전송 | | kakao_send_memo_feed | 나에게 피드 전송 | | kakao_send_memo_list | 나에게 리스트 전송 | | kakao_send_memo_location | 나에게 위치 전송 | | kakao_send_memo_commerce | 나에게 커머스 전송 | | kakao_send_memo_custom | 나에게 커스텀 템플릿 전송 | | kakao_send_to_friends_text | 친구에게 텍스트 전송 | | kakao_send_to_friends_feed | 친구에게 피드 전송 | | kakao_send_to_friends_list | 친구에게 리스트 전송 | | kakao_send_to_friends_location | 친구에게 위치 전송 | | kakao_send_to_friends_commerce | 친구에게 커머스 전송 | | kakao_send_to_friends_custom | 친구에게 커스텀 템플릿 전송 |

비즈니스 메시지 (Business Messaging)

| Tool | Description | |------|-------------| | kakao_biz_get_sender_profiles | 발신프로필 목록 조회 | | kakao_biz_get_sender_profile_detail | 발신프로필 상세 조회 | | kakao_biz_get_templates | 알림톡 템플릿 목록 조회 | | kakao_biz_get_template_detail | 알림톡 템플릿 상세 조회 | | kakao_biz_send_alimtalk | 알림톡 발송 | | kakao_biz_send_alimtalk_auth | 인증 알림톡 발송 | | kakao_biz_cancel_alimtalk | 알림톡 예약 취소 | | kakao_biz_get_alimtalk_result | 알림톡 발송 결과 조회 | | kakao_biz_send_friendtalk_text | 친구톡 텍스트 발송 | | kakao_biz_send_friendtalk_image | 친구톡 이미지 발송 | | kakao_biz_send_friendtalk_wide | 친구톡 와이드 이미지 발송 | | kakao_biz_send_friendtalk_carousel | 친구톡 캐러셀 발송 | | kakao_biz_cancel_friendtalk | 친구톡 예약 취소 | | kakao_biz_get_friendtalk_result | 친구톡 발송 결과 조회 | | kakao_biz_get_images | 등록 이미지 목록 조회 | | kakao_biz_delete_image | 등록 이미지 삭제 |

Setup

cp .env.example .env
# .env에 키 값 설정 후
npm install
npm run build
npm start           # stdio
npm run start:http  # HTTP (port 3000)

HTTP 모드에서는 아래 엔드포인트를 사용할 수 있습니다.

• GET /health - 서버 생존 확인
• GET /oauth/callback - 카카오 OAuth 리다이렉트 수신
• GET /oauth/callback/latest - 마지막으로 받은 OAuth 코드 조회
• POST /mcp - MCP Streamable HTTP endpoint

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | KAKAO_REST_API_KEY | ✅ | 카카오 REST API 키 | | KAKAO_CLIENT_SECRET | ❌ | 카카오 Client Secret | | KAKAO_REDIRECT_URI | ✅ | OAuth2 Redirect URI | | KAKAO_ACCESS_TOKEN | ❌ | 초기 액세스 토큰 | | KAKAO_REFRESH_TOKEN | ❌ | 초기 리프레시 토큰 | | KAKAO_BIZ_API_KEY | ❌ | 비즈니스 API 키 (알림톡/친구톡) | | PORT | ❌ | HTTP 포트 (기본 3000) | | TRANSPORT | ❌ | stdio | http |

로컬 자체 서버로 인증 테스트

1. .env에 KAKAO_REST_API_KEY와 KAKAO_REDIRECT_URI=http://localhost:3000/oauth/callback를 설정합니다.
2. npm run start:http로 서버를 올립니다.
3. 브라우저에서 kakao_auth_get_authorization_url 도구로 받은 URL을 엽니다.
4. 로그인 후 /oauth/callback 페이지에 표시되는 code 값을 kakao_auth_exchange_code에 넣습니다.

Docker

docker-compose up -d

MCP Client Configuration

{
  "mcpServers": {
    "kakao": {
      "command": "npx",
      "args": ["-y", "@itapi-core/mcp-kakao"],
      "env": {
        "KAKAO_REST_API_KEY": "your_key",
        "KAKAO_REDIRECT_URI": "http://localhost:3000/oauth/callback"
      }
    }
  }
}