README - Kakao Bot Mcp Server by inspirit941

Kakao Bot MCP Server

Kakao Bot MCP Server
예시
Tools
- installation
  - Step 1. developers.kakao.com 에서 카카오 애플리케이션 생성
  - Step 2. 로컬환경 설정

Model Context Protocol (MCP) server implementation that integrates the Kakao Developers API to connect an AI Agent to the Kakao Official Account.

MCP Server 구현체로, 카카오 Developers API를 AI Agent에 통합하는 예시입니다.

[!NOTE] This repository is NOT officially provided or maintained by Kakao.
It may not include complete functionality or comprehensive support.
카카오의 경우 대부분의 API가 사업자등록이 포함된 비즈니스 애플리케이션 단위로 권한을 관리하고 있으므로,
개인이 사용하기엔 제한적입니다.

참고문서: https://developers.kakao.com/docs/latest/ko/kakaotalk-message/rest-api

예시

claude desktop으로 MCP tool 실행

'나에게 메시지 전달' 결과

Tools

All tools require the __email_address__ input to identify the user's credentials.

Kakao TalkMessage API

작성시점 기준, '나에게 보내기 - 기본 템플릿' API만 지원됩니다.
참고문서: https://developers.kakao.com/docs/latest/ko/kakaotalk-message/rest-api#default-template-msg-me

send_text_template_to_me
- Description: Sends a Kakao Talk text message to me.
- Inputs:
  - __email_address__ (string, required): The email address associated with the Kakao account.
  - text (string, required, max 200 characters): The text content of the message.
  - link (object, required): An object defining the link associated with the text.
    - web_url (string, optional, uri format)
    - mobile_web_url (string, optional, uri format)
  - button_title (string, optional): The title of the button.
send_feed_template_to_me
- Description: Sends a Kakao Talk feed message to me.
- Inputs:
  - __email_address__ (string, required)
  - content (object, required): The main content block of the feed message.
    - title (string, required)
    - description (string, required)
    - image_url (string, required, uri format)
    - image_width (integer, optional)
    - image_height (integer, optional)
    - link (object, required) - defines the link for the content
      - web_url (string, optional, uri format)
      - mobile_web_url (string, optional, uri format)
      - android_execution_params (string, optional)
      - ios_execution_params (string, optional)
  - item_content (object, optional): Additional item content for the feed. (See API documentation for nested structure)
  - social (object, optional): Social information like likes, comments, etc. (See API documentation for nested structure)
  - buttons (array of objects, optional): Buttons to include with the message. (Each object requires title and link)
send_list_template_to_me
- Description: Sends a Kakao Talk list message to me.
- Inputs:
  - __email_address__ (string, required)
  - header_title (string, required): The title displayed at the top of the list.
  - contents (array of objects, required): A list of content items. Each item requires:
    - title (string, required)
    - description (string, required)
    - image_url (string, required, uri format)
    - image_width (integer, optional)
    - image_height (integer, optional)
    - link (object, required) - defines the link for the list item
      - web_url (string, optional, uri format)
      - mobile_web_url (string, optional, uri format)
      - android_execution_params (string, optional)
      - ios_execution_params (string, optional)
  - header_link (object, optional): A link for the header area. (See API documentation for nested structure)
  - buttons (array of objects, optional): Buttons to include with the message. (Each object requires title and link)
send_location_template_to_me
- Description: Sends a Kakao Talk location message to me.
- Inputs:
  - __email_address__ (string, required)
  - content (object, required): The main content block for the location message.
    - title (string, required)
    - description (string, required)
    - image_url (string, required, uri format)
    - image_width (integer, optional)
    - image_height (integer, optional)
    - link (object, required) - defines the link for the content
      - web_url (string, optional, uri format)
      - mobile_web_url (string, optional, uri format)
      - android_execution_params (string, optional)
      - ios_execution_params (string, optional)
  - address (string, required): The address of the location.
  - buttons (array of objects, optional): Buttons to include with the message. (Each object requires title and link)
  - address_title (string, optional): A title for the address.
send_calendar_template_to_me
- Description: Sends a Kakao Talk calendar message to me.
- Inputs:
  - __email_address__ (string, required)
  - content (object, required): The main content block for the calendar message.
    - title (string, required)
    - description (string, required)
    - link (object, required) - defines the link for the content
      - web_url (string, optional, uri format)
      - mobile_web_url (string, optional, uri format)
      - android_execution_params (string, optional)
      - ios_execution_params (string, optional)
    - image_url (string, optional, uri format)
  - id_type (string, required, enum: "event"): The type of calendar item.
  - id (string, required): The ID of the calendar item.
  - buttons (array of objects, optional): Buttons to include with the message. (Each object requires title and link)
send_commerce_template_to_me
- Description: Sends a Kakao Talk commerce message to me.
- Inputs:
  - __email_address__ (string, required)
  - content (object, required): The main content block for the commerce message.
    - title (string, required)
    - image_url (string, required, uri format)
    - image_width (integer, optional)
    - image_height (integer, optional)
    - link (object, required) - defines the link for the content
      - web_url (string, optional, uri format)
      - mobile_web_url (string, optional, uri format)
      - android_execution_params (string, optional)
      - ios_execution_params (string, optional)
  - commerce (object, required): Commerce-specific information.
    - regular_price (integer, required)
    - discount_price (integer, optional)
    - discount_rate (integer, optional, 0-100)
  - buttons (array of objects, optional): Buttons to include with the message. (Each object requires title and link)

Kakao TalkCalendar API

카카오 톡캘린더 API를 통해 사용자의 캘린더를 조회하고 관리하는 도구입니다.
- 작성시점 기준 '사용자 캘린더 - 목록 가져오기, 서브 캘린더 생성 / 수정 / 삭제' 기능만 지원됩니다.
- 톡캘린더 API는 카카오에 사용 권한을 신청해야 합니다. 신청 방법은 https://developers.kakao.com/docs/latest/ko/talkcalendar/common#policy-request-permission 를 참고하세요.
참고문서: https://developers.kakao.com/docs/latest/ko/talkcalendar/rest-api

get_calendar_list
- Description: Retrieves the list of user calendars.
- Inputs:
  - __email_address__ (string, required): The email address associated with the Kakao account.
create_sub_calendar
- Description: Creates a new sub-calendar for the user.
- Inputs:
  - __email_address__ (string, required): The email address associated with the Kakao account.
  - name (string, required): The name of the sub calendar.
  - color (string, optional): The default color for events in the calendar.
  - reminder (integer, optional): The default reminder time for non-all-day events in minutes.
  - reminder_all_day (integer, optional): The default reminder time for all-day events in minutes.
update_sub_calendar
- Description: Updates an existing sub-calendar.
- Inputs:
  - __email_address__ (string, required): The email address associated with the Kakao account.
  - calendar_id (string, required): The ID of the sub calendar to update.
  - name (string, optional): The new name for the sub calendar.
  - color (string, optional): The new default color for events in the calendar.
  - reminder (integer, optional): The new default reminder time for non-all-day events in minutes.
  - reminder_all_day (integer, optional): The new default reminder time for all-day events in minutes.
delete_sub_calendar
- Description: Deletes a user's sub-calendar.
- Inputs:
  - __email_address__ (string, required): The email address associated with the Kakao account.
  - calendar_id (string, required): The ID of the sub calendar to delete.

installation

requirements: Python 3.13+

카카오 계정 필요

Step 1. developers.kakao.com 에서 카카오 애플리케이션 생성

카카오 신규 애플리케이션 생성 방법은 quick start문서를 참고합니다.

메시지 API를 활성화하기 위한 추가작업

사이트 등록

"내 애플리케이션 > 앱 설정 > 플랫폼" 의 Web에서 사이트 도메인으로 http://localhost:8000 등록

비즈 앱 등록

비즈 앱 등록. 사업자번호가 없어도 "개인 개발자 비즈 앱" 등록이 가능하다.

카카오 로그인 활성화

카카오 로그인을 활성화한다.

동의항목 설정

제품 설정 > 카카오 로그인 > 동의항목에서 '닉네임', '카카오계정(이메일)', '카카오톡 메시지 전송' 을 활성화한다.
OpenID 활성화한다.
톡캘린더 API가 필요한 경우 https://developers.kakao.com/docs/latest/ko/talkcalendar/common#policy-request-permission 를 참고해서 사용 권한을 신청해야 한다.

Step 2. 로컬환경 설정

로컬에 uv가 설치되어 있어야 한다.

git clone git@github.com:inspirit941/kakao-bot-mcp-server.git
cd kakao-bot-mcp-server
pip install uv
uv sync

# inspector 실행
npx @modelcontextprotocol/inspector uv --directory .  run mcp-kakao

# MCP server 실행
uv run mcp-kakao

정상적으로 동작하려면 두 개의 파일이 필요하다. .accounts.json, .kauth.json 프로젝트 root 경로에 아래 파일을 생성한다.

.accounts.json


{
    "accounts": [
        {
            "email": "your-email@kakao.com",
            "account_type": "personal",
            "extra_info": "Additional info that you want to tell Claude: E.g. 'Contains Family Calendar'"
        }
    ]
}

email: 카카오 계정 이메일주소.
account_type: personal 고정.
extra_info: MCP server에 전달할 추가정보.

.kauth.json

{
  "web": {
    "client_id": "rest-api-key",
    "auth_uri": "https://kauth.kakao.com/oauth/authorize",
    "token_uri": "https://kauth.kakao.com/oauth/token",
    "client_secret": "your_client_secret",
    "redirect_uris": ["http://localhost:8000/code"],
    "revoke_uri": "https://kapi.kakao.com/v2/user/revoke/scopes",
    "token_info_uri": "https://kauth.kakao.com/oauth/tokeninfo"
  }
}

client_id: 카카오 애플리케이션에서 제공하는 REST_API key
client_secret: 카카오 애플리케이션에서 발급받을 수 있는 client_secret. 임의의 문자열을 넣어도 동작함
나머지 필드는 고정.

claude desktop 설정

{
  "mcpServers": {
    "mcp-kakao": {
      "command": "uv",
      "args": [
        "--directory",
        "your-project-path/kakao-bot-mcp-server",
        "run",
        "mcp-kakao"
      ]
    }
  }
}

동작 방식

LLM이 MCP Tool을 실행하면

프로젝트 root 경로에 .oauth2.<카카오메일주소>.json 파일이 있는지 확인한다.
- 파일이 없을 경우, 웹 브라우저에 카카오 OAuth2 서버에 로그인 화면을 띄운다. (https://accounts.kakao.com/login?continue=...)
- 파일이 있을 경우, 토큰이 만료되지 않았는지 확인한다. 만료되었다면, refresh token으로 재발급받는다. refresh token도 만료되었을 경우, tool에서 로그인할 수 있는 url 주소를 리턴한다.
로그인에 성공하면, 프로젝트 root 경로에 .oauth2.<카카오메일주소>.json 이름으로 access_token 정보를 저장한다.

MCP tool은 json 파일의 access token을 사용하는 구조.