Kakao Bot Mcp Server

Kakao Bot MCP 服务

• Kakao Bot MCP 服务
• 示例
• 工具
  • 安装
    • 步骤 1. 在 developers.kakao.com 创建 Kakao 应用
    • 步骤 2. 配置本地环境

Model Context Protocol (MCP) 服务实现，通过集成 Kakao Developers API，将 AI Agent 连接到 Kakao 官方账号。

这是 MCP 服务的一种实现示例，展示了如何将 Kakao Developers API 集成到 AI Agent 中。

说明

此代码库并非由 Kakao 官方提供或维护。
它可能不包含完整的功能，也不提供全面的支持。
Kakao 的大多数 API 都以包含营业执照的商业应用为单位管理权限，因此，
个人使用会受到限制。

参考文档：https://developers.kakao.com/docs/latest/ko/kakaotalk-message/rest-api

---

示例

使用 Claude 桌面应用运行 MCP 工具

“发送消息给我”的结果

工具

所有工具都需要输入 __email_address__，以识别用户凭据。

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

   • 描述：向我发送 Kakao Talk 文本消息。
   • 输入：
     • __email_address__（string，必填）：与 Kakao 账号关联的电子邮件地址。
     • text（string，必填，最多 200 个字符）：消息的文本内容。
     • link（object，必填）：定义与文本关联链接的对象。
       • web_url（string，可选，uri 格式）
       • mobile_web_url（string，可选，uri 格式）
     • button_title（string，可选）：按钮标题。

2. send_feed_template_to_me

   • 描述：向我发送 Kakao Talk 动态消息。
   • 输入：
     • __email_address__（string，必填）
     • content（object，必填）：动态消息的主要内容块。
       • title（string，必填）
       • description（string，必填）
       • image_url（string，必填，uri 格式）
       • image_width（integer，可选）
       • image_height（integer，可选）
       • link（object，必填）- 定义内容的链接
         • web_url（string，可选，uri 格式）
         • mobile_web_url（string，可选，uri 格式）
         • android_execution_params（string，可选）
         • ios_execution_params（string，可选）
     • item_content（object，可选）：动态消息的附加条目内容。（嵌套结构请参阅 API 文档）
     • social（object，可选）：点赞、评论等社交信息。（嵌套结构请参阅 API 文档）
     • buttons（array of objects，可选）：消息中包含的按钮。（每个对象都需要 title 和 link）

3. **send_list_template_to_me** * 描述：向我发送一条 Kakao Talk 列表消息。 * 输入： * `__email_address__`（字符串，必填） * `header_title`（字符串，必填）：显示在列表顶部的标题。 * `contents`（对象数组，必填）：内容项列表。每个项都需要： * `title`（字符串，必填） * `description`（字符串，必填） * `image_url`（字符串，必填，uri 格式） * `image_width`（整数，可选） * `image_height`（整数，可选） * `link`（对象，必填）- 定义列表项的链接 * `web_url`（字符串，可选，uri 格式） * `mobile_web_url`（字符串，可选，uri 格式） * `android_execution_params`（字符串，可选） * `ios_execution_params`（字符串，可选） * `header_link`（对象，可选）：标题区域的链接。（嵌套结构请参阅 API 文档） * `buttons`（对象数组，可选）：消息中包含的按钮。（每个对象都需要 `title` 和 `link`）

4. send_location_template_to_me

   • 描述：向我发送一条 Kakao Talk 位置消息。
   • 输入：
     • __email_address__（字符串，必填）
     • content（对象，必填）：位置消息的主要内容块。
       • title（字符串，必填）
       • description（字符串，必填）
       • image_url（字符串，必填，uri 格式）
       • image_width（整数，可选）
       • image_height（整数，可选）
       • link（对象，必填）- 定义内容的链接
         • web_url（字符串，可选，uri 格式）
         • mobile_web_url（字符串，可选，uri 格式）
         • android_execution_params（字符串，可选）
         • ios_execution_params（字符串，可选）
     • address（字符串，必填）：位置的地址。
     • buttons（对象数组，可选）：消息中包含的按钮。（每个对象都需要 title 和 link）
     • address_title（字符串，可选）：地址的标题。

5. send_calendar_template_to_me

   • 描述：向我发送一条 Kakao Talk 日历消息。
   • 输入：
     • __email_address__（字符串，必填）
     • content（对象，必填）：日历消息的主要内容块。
       • title（字符串，必填）
       • description（字符串，必填）
       • link（对象，必填）- 定义内容的链接
         • web_url（字符串，可选，uri 格式）
         • mobile_web_url（字符串，可选，uri 格式）
         • android_execution_params（字符串，可选）
         • ios_execution_params（字符串，可选）
       • image_url（字符串，可选，uri 格式）
     • id_type（字符串，必填，枚举："event"）：日历项目的类型。
     • id（字符串，必填）：日历项目的 ID。
     • buttons（对象数组，可选）：消息中包含的按钮。（每个对象都需要 title 和 link）

6. send_commerce_template_to_me

   • Description：向我发送 Kakao Talk 商务消息。
   • Inputs：
     • __email_address__（字符串，必填）
     • content（对象，必填）：商务消息的主要内容区块。
       • title（字符串，必填）
       • image_url（字符串，必填，uri 格式）
       • image_width（整数，可选）
       • image_height（整数，可选）
       • link（对象，必填）- 定义内容的链接
         • web_url（字符串，可选，uri 格式）
         • mobile_web_url（字符串，可选，uri 格式）
         • android_execution_params（字符串，可选）
         • ios_execution_params（字符串，可选）
     • commerce（对象，必填）：商务专属信息。
       • regular_price（整数，必填）
       • discount_price（整数，可选）
       • discount_rate（整数，可选，0-100）
     • buttons（对象数组，可选）：消息中包含的按钮。（每个对象都需要 title 和 link）

Kakao TalkCalendar API

• 通过 Kakao TalkCalendar API 查询和管理用户的日历的工具。
  • 截至编写时，仅支持“用户日历 - 获取列表、创建 / 修改 / 删除子日历”功能。
  • TalkCalendar API 需要向 Kakao 申请使用权限。申请方法请参阅 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：获取用户日历列表。
   • Inputs：
     • __email_address__（字符串，必填）：与 Kakao 账号关联的电子邮件地址。

2. create_sub_calendar

   • Description：为用户创建新的子日历。
   • Inputs：
     • __email_address__（字符串，必填）：与 Kakao 账号关联的电子邮件地址。
     • name（字符串，必填）：子日历的名称。
     • color（字符串，可选）：日历中事件的默认颜色。
     • reminder（整数，可选）：非全天事件的默认提醒时间，单位为分钟。
     • reminder_all_day（整数，可选）：全天事件的默认提醒时间，单位为分钟。

3. update_sub_calendar

   • Description：更新现有子日历。
   • Inputs：
     • __email_address__（字符串，必填）：与 Kakao 账号关联的电子邮件地址。
     • calendar_id（字符串，必填）：要更新的子日历 ID。
     • name（字符串，可选）：子日历的新名称。
     • color（字符串，可选）：日历中事件的新默认颜色。
     • reminder（整数，可选）：非全天事件的新默认提醒时间，单位为分钟。
     • reminder_all_day（整数，可选）：全天事件的新默认提醒时间，单位为分钟。

4. delete_sub_calendar

   • Description：删除用户的子日历。
   • Inputs：
     • __email_address__（字符串，必填）：与 Kakao 账号关联的电子邮件地址。
     • calendar_id（字符串，必填）：要删除的子日历 ID。

安装

要求：Python 3.13+

需要 Kakao 账号

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 [email protected]: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": "[email protected]",
            "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을 사용하는 구조.