KakaoTalk Message

@appmonster/mcp-kakao

通过 Kakao Developers 消息 API 发送 KakaoTalk 消息的 MCP 服务：Agent 可以向已连接账号自己的聊天（나와의 채팅）或同样已关联应用的好友发送消息，也可以列出好友。写入操作可由人工审批后执行（OK Agent）。

KakaoTalk 消息 MCP 服务 — 发送给自己 / 发送给好友 / 好友列表。无需安装应用，就能向老板的手机发送通知的最简途径。

通知类消息（商业消息）是需要与 Kakao 官方代理商签约的独立渠道。本软件包仅涉及个人或小型企业可立即使用的 Kakao Developers 消息 API。通知类消息已列入路线图。

工具

工具	访问权限	功能
kakao_me	读取	查看已连接的账号和授权项目（用于检查连接）
kakao_send_to_me	写入	向与自己的聊天发送文本 / 信息流卡片（包含链接和按钮）
kakao_list_friends	读取	已关联应用的好友列表（uuid）
kakao_send_to_friends	写入	向最多 5 位好友的 uuid 发送消息，并分别返回成功 / 失败状态

设置（5 分钟，仅需 1 次）

1. 前往 https://developers.kakao.com → 我的应用程序 → 添加应用。复制 应用密钥 > REST API 密钥。
2. 平台 > Web：注册用于消息链接的域名（例如：https://okagent.kr）。
3. Kakao 登录 > 启用 ON，在 Redirect URI 中添加 http://localhost:8788/callback。
4. Kakao 登录 > 授权项目：将 KakaoTalk 消息发送 (talk_message) 设为“选择性同意”。如需使用好友功能，还需申请 KakaoTalk 社交 > 好友列表权限，并添加 friends 授权项目。
5. 在浏览器中登录 1 次：

KAKAO_REST_API_KEY=… npx @appmonster/mcp-kakao auth

令牌会保存到 ~/.config/kmcp/kakao/<app>.json，并自动续期（refresh ≈ 2 个月）。

6. MCP 客户端配置：

{
  "mcpServers": {
    "kakao": {
      "command": "npx",
      "args": ["-y", "@appmonster/mcp-kakao"],
      "env": { "KAKAO_REST_API_KEY": "…" }
    }
  }
}

如果容器等环境难以保存文件，可以通过 env 传入 KAKAO_REFRESH_TOKEN。如果在应用中启用了 Client Secret，也需要设置 KAKAO_CLIENT_SECRET。

发送时进行人工审批（可选）

"OKAGENT_API_KEY": "ok_…"

即使不设置该选项，写入工具也不会直接执行：首次调用会返回预览和 confirm_token，只有你在聊天中同意后，Agent 才会再次调用。使用 OK Agent 密钥（免费，每月 200 次）后，请求会改为发送到你的手机；你可以在 KakaoTalk 中批准，并查看日志。对于完全信任的脚本，可设置 KMCP_WRITE_MODE=direct 关闭检查。

消息规范

只提供 text（≤200 字符）时发送文本消息；提供 title 或 imageUrl 时发送信息流卡片。url 必须使用已注册到应用 Web 平台的域名，按钮才能正常打开。最多可添加 2 个按钮。

限制

• 发送给自己无需审核即可立即执行。发送给好友时，对方也必须关联应用，且有每日发送限额（错误 -532）。
• 错误代码提示：-3 功能未启用，-401 令牌过期（重新运行 auth），-402 授权项目不足。

开发

pnpm --filter @appmonster/mcp-kakao test