Kakao Bot MCP Server

## Kakao Bot MCP Server <!-- TOC --> - [Kakao Bot MCP Server](#kakao-bot-mcp-server) - [예시](#예시) - [Tools](#tools) - [installation](#installation) - [Step 1. developers.kakao.com 에서 카카오 애플리케이션 생성](#step-1-developerskakaocom-에서-카카오-애플리케이션-생성) - [Step 2. 로컬환경 설정](#step-2-로컬환경-설정) <!-- /TOC --> [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol) server implementation that integrates the Kakao Developers API to connect an AI Agent to the Kakao Official Account. MCP Server 구현체로, 카카오 Developers API를 AI Agent에 통합하는 예시입니다. <br> > [!NOTE] > This repository is NOT officially provided or maintained by Kakao. <br> > It may not include complete functionality or comprehensive support. <br> > 카카오의 경우 대부분의 API가 사업자등록이 포함된 비즈니스 애플리케이션 단위로 권한을 관리하고 있으므로, <br> > 개인이 사용하기엔 제한적입니다. <br> 참고문서: https://developers.kakao.com/docs/latest/ko/kakaotalk-message/rest-api --- ## 예시 <img src="https://gitlab.com/-/project/69172217/uploads/89b84962ae9233c26bddd6318f60f97a/%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA_2025-05-03_%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE_2.36.09.png" alt="스크린샷_2025-05-03_오후_2.36.09" width="550"> <br> claude desktop으로 MCP tool 실행 <img src="https://gitlab.com/-/project/69172217/uploads/e27b0f53e2776e6371fd2f5a0745299a/%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA_2025-05-03_%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE_2.37.25.png" alt="스크린샷_2025-05-03_오후_2.37.25" width="330"> <br> '나에게 메시지 전달' 결과 ## Tools All tools require the `__email_address__` input to identify the user's credentials. <details> <summary><h3>Kakao TalkMessage API</h3></summary> - 작성시점 기준, '나에게 보내기 - 기본 템플릿' API만 지원됩니다. - 참고문서: https://developers.kakao.com/docs/latest/ko/kakaotalk-message/rest-api#default-template-msg-me 1. **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. 2. **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`) 3. **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`) 4. **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. 5. **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`) 6. **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`) </details> <details> <summary><h3>Kakao TalkCalendar API</h3></summary> - 카카오 톡캘린더 API를 통해 사용자의 캘린더를 조회하고 관리하는 도구입니다. - 작성시점 기준 '사용자 캘린더 - 목록 가져오기, 서브 캘린더 생성 / 수정 / 삭제' 기능만 지원됩니다. - 톡캘린더 API는 카카오에 사용 권한을 신청해야 합니다. 신청 방법은 https://developers.kakao.com/docs/latest/ko/talkcalendar/common#policy-request-permission 를 참고하세요. - 참고문서: https://developers.kakao.com/docs/latest/ko/talkcalendar/rest-api 1. **get_calendar_list** * Description: Retrieves the list of user calendars. * Inputs: * `__email_address__` (string, required): The email address associated with the Kakao account. 2. **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. 3. **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. 4. **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. </details> ### installation requirements: Python 3.13+ 카카오 계정 필요 #### Step 1. developers.kakao.com 에서 카카오 애플리케이션 생성 카카오 신규 애플리케이션 생성 방법은 [quick start](https://developers.kakao.com/docs/latest/ko/getting-started/quick-start#create)문서를 참고합니다. <details> <summary>메시지 API를 활성화하기 위한 추가작업</summary>  "내 애플리케이션 > 앱 설정 > 플랫폼" 의 Web에서 사이트 도메인으로 http://localhost:8000 등록 <br>  비즈 앱 등록. 사업자번호가 없어도 "개인 개발자 비즈 앱" 등록이 가능하다. <br>  카카오 로그인을 활성화한다. <br>  - 제품 설정 > 카카오 로그인 > 동의항목에서 '닉네임', '카카오계정(이메일)', '카카오톡 메시지 전송' 을 활성화한다. - OpenID 활성화한다. - 톡캘린더 API가 필요한 경우 https://developers.kakao.com/docs/latest/ko/talkcalendar/common#policy-request-permission 를 참고해서 사용 권한을 신청해야 한다. </details> #### Step 2. 로컬환경 설정 로컬에 uv가 설치되어 있어야 한다. ```sh 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 ```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 ```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 설정 ```json { "mcpServers": { "mcp-kakao": { "command": "uv", "args": [ "--directory", "your-project-path/kakao-bot-mcp-server", "run", "mcp-kakao" ] } } } ``` **동작 방식** <br> 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을 사용하는 구조.