卡卡奥机器人MCP服务器
项目介绍
Kakao Bot MCP Server
<!-- TOC --> <!-- /TOC -->MCP（模型上下文协议）服务器实现，集成 Kakao 开发者 API，以连接 AI 代理到 Kakao 官方账号。
这是一个 MCP 服务器实现示例，它将 Kakao 开发者 API 集成到 AI 代理中。
<br><br>[!NOTE] 本仓库并非由 Kakao 官方提供或维护。<br> 可能不包括完整的功能或全面的支持。<br> 对于大多数 API，Kakao 通常以包含企业注册信息的企业应用程序为单位来管理权限，因此对于个人用户来说可能具有一定的限制性。
参考文档：https://developers.kakao.com/docs/latest/ko/kakaotalk-message/rest-api
示例
<img src="https://gips0.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://gips0.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__ 输入来识别用户的凭证。
- 截至撰写时，仅支持“发送消息给我 - 基本模板”API。
- 参考文档：https://developers.kakao.com/docs/latest/ko/kakaotalk-message/rest-api#default-template-msg-me
-
send_text_template_to_me
- 描述：向我发送 Kakao Talk 文本消息。
- 输入：
__email_address__(字符串，必需)：与 Kakao 账户关联的电子邮件地址。text(字符串，必需，最大 200 字符)：消息的文本内容。link(对象，必需)：定义与文本关联的链接的对象。web_url(字符串，可选，uri 格式)mobile_web_url(字符串，可选，uri 格式)
button_title(字符串，可选)：按钮的标题。
-
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)
-
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)
-
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(字符串，可选)：地址的标题。
-
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)
-
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)
- 通过 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
-
get_calendar_list
- 描述：获取用户日历列表。
- 输入：
__email_address__(字符串，必需)：与 Kakao 账户关联的电子邮件地址。
-
create_sub_calendar
- 描述：为用户创建新的子日历。
- 输入：
__email_address__(字符串，必需)：与 Kakao 账户关联的电子邮件地址。name(字符串，必需)：子日历的名称。color(字符串，可选)：日历事件的默认颜色。reminder(整数，可选)：非全天事件的默认提醒时间（分钟）。reminder_all_day(整数，可选)：全天事件的默认提醒时间（分钟）。
-
update_sub_calendar
- 描述：更新现有的子日历。
- 输入：
__email_address__(字符串，必需)：与 Kakao 账户关联的电子邮件地址。calendar_id(字符串，必需)：要更新的子日历的 ID。name(字符串，可选)：子日历的新名称。color(字符串，可选)：日历事件的新默认颜色。reminder(整数，可选)：非全天事件的新默认提醒时间（分钟）。reminder_all_day(整数，可选)：全天事件的新默认提醒时间（分钟）。
-
delete_sub_calendar
- 描述：删除用户的子日历。
- 输入：
__email_address__(字符串，必需)：与 Kakao 账户关联的电子邮件地址。calendar_id(字符串，必需)：要删除的子日历的 ID。
安装
需求：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 并申请使用权限。
步骤 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 服务器
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 服务器的附加信息。
.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 文件中的访问令牌。