技术文档摘要

Kakao Bot MCP Server

<!-- 目录 -->

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

<!-- 目录结束 -->

基于 Model Context Protocol (MCP) 的服务器实现，集成 Kakao Developers API，以连接 AI 代理到 Kakao 官方账号。

这是一个 MCP 服务器实现示例，它将 Kakao Developers API 集成到 AI 代理中。

<br>

[!NOTE] 本仓库并非由 Kakao 官方提供或维护。
可能不包含完整的功能或全面的支持。
对于大多数 API，Kakao 通常以包含企业注册信息的企业应用单位来管理权限，因此对于个人使用来说可能有限制。

<br>

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

---

示例

<img src="https://gips2.baidu.com/it/u=2347609853,2258156143&fm=3081&app=3081&f=PNG?w=1458&h=1508" alt="截图_2025-05-03_下午_2.36.09" width="550"> <br>

通过 claude desktop 运行 MCP 工具

<img src="https://gips3.baidu.com/it/u=1581137802,4133899476&fm=3081&app=3081&f=PNG?w=850&h=1136" alt="截图_2025-05-03_下午_2.37.25" width="330"> <br>

“向我发送消息”的结果

工具

所有工具都需要 __email_address__ 输入来识别用户凭证。

<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

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

2. send_feed_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（字符串，可选）
     • item_content（对象，可选）：动态消息的附加项目内容。（参见 API 文档中的嵌套结构）
     • social（对象，可选）：社交信息，如点赞、评论等。（参见 API 文档中的嵌套结构）
     • buttons（对象数组，可选）：要包含在消息中的按钮。（每个对象需要 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

   • 描述：向我发送 Kakao Talk 商业消息。
   • 输入：
     • __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）

</details> <details> <summary><h3>Kakao TalkCalendar API</h3></summary>

• 通过 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

   • 描述：获取用户日历列表。
   • 输入：
     • __email_address__（字符串，必需）：与 Kakao 账户关联的电子邮件地址。

2. create_sub_calendar

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

3. update_sub_calendar

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

4. delete_sub_calendar

   • 描述：删除用户的子日历。
   • 输入：
     • __email_address__（字符串，必需）：与 Kakao 账户关联的电子邮件地址。
     • calendar_id（字符串，必需）：要删除的子日历的 ID。

</details>

安装

需求：Python 3.13+

需要 Kakao 账户

步骤 1. 在 developers.kakao.com 创建 Kakao 应用程序

创建 Kakao 新应用程序的方法，请参阅 快速开始 文档。

<details> <summary>激活消息 API 所需的额外操作</summary>

在“我的应用程序 > 应用设置 > 平台”的 Web 中，将站点域名注册为 http://localhost:8000

<br>

注册业务应用。即使没有企业编号，也可以注册“个人开发者业务应用”。

<br>

激活 Kakao 登录。

<br>

• 在“产品设置 > Kakao 登录 > 同意项”中，激活“昵称”、“Kakao 账户（电子邮件）”、“KakaoTalk 消息发送”。
• 激活 OpenID。
• 如果需要 TalkCalendar API，请参阅 https://developers.kakao.com/docs/latest/ko/talkcalendar/common#policy-request-permission 并申请使用权限。

</details>

步骤 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。在项目根目录下创建以下文件。

.accounts.json

{
    "accounts": [
        {
            "email": "your-email@kakao.com",
            "account_type": "personal",
            "extra_info": "要告诉 Claude 的附加信息：例如 '包含家庭日历'"
        }
    ]
}

• email：Kakao 账户的电子邮件地址。
• 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：Kakao 应用程序提供的 REST_API 密钥。
• client_secret：可以从 Kakao 应用程序获取的 client_secret。输入任意字符串也可工作。
• 其他字段是固定的。

Claude desktop 设置

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

工作方式

<br>

当 LLM 执行 MCP 工具时，

• 检查项目根目录下是否存在 .oauth2.<Kakao邮箱地址>.json 文件。
  • 如果不存在，会在浏览器中打开 Kakao OAuth2 服务器的登录页面（https://accounts.kakao.com/login?continue=...）。
  • 如果存在，会检查令牌是否已过期。如果已过期，则使用刷新令牌重新获取。如果刷新令牌也已过期，工具会返回一个可以登录的 URL 地址。
• 成功登录后，在项目根目录下以 .oauth2.<Kakao邮箱地址>.json 的名称保存访问令牌信息。

MCP 工具使用 JSON 文件中的访问令牌。