Kakao消息服务集成

一个实现Kakao Developers API与AI Agent集成的MCP服务器,支持发送多种类型的Kakao Talk消息和管理日历。

  • by inspirit941
  • Python
  • 本地部署
  • 17 星标
  • 更新于
在 GitHub 查看 inspirit941/mcp-server

使用说明

Kakao Bot MCP服务器

模型上下文协议(MCP) 服务器实现,集成Kakao Developers API,将AI代理连接到Kakao官方帐户。

MCP Server实现,示例将Kakao Developers API集成到AI Agent中。


[!注意] 此存储库不是由Kakao正式提供或维护的。
它可能不包括完整的功能或全面的支持。
在Kakao中,大多数API都以包含运营商注册的业务应用程序为单位管理权限。
个人使用有限。


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


示例


用claude desktop运行MCP tool


“向我传达信息”结果

工具

所有工具都需要 __email_address__ 用于标识用户凭据的输入。

Kakao TalkMessage API

  • 仅支持“发送给我-默认模板”API。
  • 참고문서: https://developers.kakao.com/docs/latest/ko/kakaotalk-message/rest-api#default-模板msg me
  1. send_text_template_to_me

    • 描述:向我发送Kakao Talk短信。
    • 输入:
      • __email_address__ (string,必填):与Kakao帐户关联的电子邮件地址。
      • text (字符串,必填,最多200个字符):消息的文本内容。
      • link (object,必填):定义与文本关联的链接的对象。
        • web_url (字符串,可选,uri格式)
        • mobile_web_url (字符串,可选,uri格式)
      • button_title (字符串,可选):按钮的标题。
  2. send_feed_template_to_me

    • 描述:向我发送Kakao Talk feed消息。
    • 输入:
      • __email_address__ (字符串,必填)
      • content (object,必填):提要消息的主要内容块。
        • title (字符串,必填)
        • description (字符串,必填)
        • image_url (字符串,必填,uri格式)
        • image_width (整数,可选)
        • image_height (整数,可选)
        • link (object,必填)-定义内容的链接
          • web_url (字符串,可选,uri格式)
          • mobile_web_url (字符串,可选,uri格式)
          • android_execution_params (字符串,可选)
          • ios_execution_params (字符串,可选)
      • item_content (object,可选):提要的其他项目内容。(有关嵌套结构,请参见API文档)
      • social (object,可选):点赞、评论等社交信息。(有关嵌套结构,请参见API文档)
      • buttons (对象数组,可选):消息中包含的按钮。(每个对象都需要 title 和 link)
  3. send_list_template_to_me

    • 描述:向我发送Kakao Talk列表消息。
    • 输入:
      • __email_address__ (字符串,必填)
      • header_title (string,必填):显示在列表顶部的标题。
      • contents (对象数组,必填):内容项列表。每个项目都需要:
        • title (字符串,必填)
        • description (字符串,必填)
        • image_url (字符串,必填,uri格式)
        • image_width (整数,可选)
        • image_height (整数,可选)
        • link (object,必填)-定义列表项的链接
          • web_url (字符串,可选,uri格式)
          • mobile_web_url (字符串,可选,uri格式)
          • android_execution_params (字符串,可选)
          • ios_execution_params (字符串,可选)
      • header_link (object,可选):标题区域的链接。(有关嵌套结构,请参见API文档)
      • buttons (对象数组,可选):消息中包含的按钮。(每个对象都需要 title 和 link)
  4. send_location_template_to_me

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

    • 描述:向我发送Kakao Talk日历消息。
    • 输入:
      • __email_address__ (字符串,必填)
      • content (object,必填):日历消息的主要内容块。
        • title (字符串,必填)
        • description (字符串,必填)
        • link (object,必填)-定义内容的链接
          • web_url (字符串,可选,uri格式)
          • mobile_web_url (字符串,可选,uri格式)
          • android_execution_params (字符串,可选)
          • ios_execution_params (字符串,可选)
        • image_url (字符串,可选,uri格式)
      • id_type (string,必填,枚举:“event”):日历项的类型。
      • id (字符串,必填):日历项的ID。
      • buttons (对象数组,可选):消息中包含的按钮。(每个对象都需要 title 和 link)
  6. send_commerce_template_tome

    • 描述:向我发送Kakao Talk商务消息。
    • 输入:
      • __email_address__ (字符串,必填)
      • content (object,必填):商业消息的主要内容块。
        • title (字符串,必填)
        • image_url (字符串,必填,uri格式)
        • image_width (整数,可选)
        • image_height (整数,可选)
        • link (object,必填)-定义内容的链接
          • 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

  • 通过KakaoTalk日历API查看和管理用户日历的工具。
    • 仅支持创建时的“用户日历-导入列表,创建/修改/删除子日历”功能。
    • Talk日历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__ (string,必填):与Kakao帐户关联的电子邮件地址。
  2. create_sub_calendar

    • 说明:为用户创建新的子日历。
    • 输入:
      • __email_address__ (string,必填):与Kakao帐户关联的电子邮件地址。
      • name (string,必填):子日历的名称。
      • color (字符串,可选):日历中事件的默认颜色。
      • reminder (整数,可选):非全天事件的默认提醒时间(分钟)。
      • reminder_all_day (整数,可选):全天事件的默认提醒时间,单位为分钟。
  3. update_sub_calendar

    • 说明:更新现有子日历。
    • 输入:
      • __email_address__ (string,必填):与Kakao帐户关联的电子邮件地址。
      • calendar_id (字符串,必填):要更新的子日历的ID。
      • name (字符串,可选):子日历的新名称。
      • color (字符串,可选):日历中事件的新默认颜色。
      • reminder (整数,可选):非全天事件的新默认提醒时间,单位为分钟。
      • reminder_all_day (整数,可选):全天事件的新默认提醒时间,单位为分钟。
  4. delete_sub_calendar

    • 说明:删除用户的子日历。
    • 输入:
      • __email_address__ (string,必填):与Kakao帐户关联的电子邮件地址。
      • calendar_id (字符串,必填):要删除的子日历的ID。

安装

要求:Python 3.13+

需要Kakao账号

Step 1.在developers.kakao.com上创建Kakao应用程序

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

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

从“我的应用程序>应用程序设置>平台”中的Web到站点域http://localhost:8000注册


商务应用程序注册。即使没有商家号,也可以注册“个人开发者商务应用程序”。


激活Kakao登录。


  • 在产品设置>Kakao登录>同意项目中,激活“昵称”、“Kakao账号(电子邮件)”、“发送Kakao Talk信息”。
  • 激活OpenID。
  • 如果需要Talk日历APIhttps://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:Kakao账号电子邮件地址。
  • account_type:个人고정.
  • extra_info:要传递给MCP服务器的其他信息。

你好。

{
  "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 key
  • client_secret:可以从Kakao应用程序获得的client_secret。可以添加任意字符串
  • 其余字段为固定字段。

claude desktop设置

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

动作方式


LLM运行MCP Tool时

  • 在项目根路径中 .oauth2.<카카오메일주소>.json 确认是否有文件。
    • 如果没有文件,则在Web浏览器中显示登录到Kakao OAuth2服务器的屏幕。 (https://accounts.kakao.com/login?continue=...)
    • 如果有文件,请确保令牌未过期。如果到期,将通过refresh token重新发放。如果refresh token也过期,将返回tool可以登录的url地址。
  • 如果登录成功,请访问项目根路径 .oauth2.<카카오메일주소>.json 以名称保存access_token信息。

MCP tool使用json文件的access token结构。