Information
## Kakao Bot MCP Server
- [Kakao Bot MCP Server](#kakao-bot-mcp-server)
- [예시](#예시)
- [Tools](#tools)
- [installation](#installation)
- [Step 1. developers.kakao.com 에서 카카오 애플리케이션 생성](#step-1-developerskakaocom-에서-카카오-애플리케이션-생성)
- [Step 2. 로컬환경 설정](#step-2-로컬환경-설정)
[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에 통합하는 예시입니다.
> [!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.
- 작성시점 기준, '나에게 보내기 - 기본 템플릿' 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\`)
- 카카오 톡캘린더 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.
### installation
requirements: Python 3.13+
카카오 계정 필요
#### Step 1. developers.kakao.com 에서 카카오 애플리케이션 생성
카카오 신규 애플리케이션 생성 방법은 [quick start](https://developers.kakao.com/docs/latest/ko/getting-started/quick-start#create)문서를 참고합니다.
 비즈 앱 등록. 사업자번호가 없어도 "개인 개발자 비즈 앱" 등록이 가능하다.
 카카오 로그인을 활성화한다.
 - 제품 설정 > 카카오 로그인 > 동의항목에서 '닉네임', '카카오계정(이메일)', '카카오톡 메시지 전송' 을 활성화한다. - OpenID 활성화한다. - 톡캘린더 API가 필요한 경우 https://developers.kakao.com/docs/latest/ko/talkcalendar/common#policy-request-permission 를 참고해서 사용 권한을 신청해야 한다.
#### 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"
]
\}
\}
\}
\`\`\`
**동작 방식**
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을 사용하는 구조.
> [!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
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\`)
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
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.
메시지 API를 활성화하기 위한 추가작업
 "내 애플리케이션 > 앱 설정 > 플랫폼" 의 Web에서 사이트 도메인으로 http://localhost:8000 등록 비즈 앱 등록. 사업자번호가 없어도 "개인 개발자 비즈 앱" 등록이 가능하다.
 카카오 로그인을 활성화한다.
 - 제품 설정 > 카카오 로그인 > 동의항목에서 '닉네임', '카카오계정(이메일)', '카카오톡 메시지 전송' 을 활성화한다. - OpenID 활성화한다. - 톡캘린더 API가 필요한 경우 https://developers.kakao.com/docs/latest/ko/talkcalendar/common#policy-request-permission 를 참고해서 사용 권한을 신청해야 한다.
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을 사용하는 구조.