kmsg MCP

kmsg-mcp

KakaoTalk官方API？ 没有。 爬墙？ 现在不用做了。 bash install.sh 一次的话，在Claude Code上读Kakaotalk后发送结束。

______________________________________________________________________

为什么要做

AI时代好像只有我落后了，大家都有过一次吧？

有很多人说MCP和代理，但要想实现一个KakaoTalk的自动化，没有官方API，需要转Celenium、贴ADB、骑星星墙。在这个过程中放弃的人很多。

所以制作了。 在AI知识差距中感受FOMO，让辛苦爬墙的人一下子解决。

只要有一个MCP服务器，Claude Code就会用自然语言控制KakaoTalk。“给洪吉童发Kakaotalk”的话 真的发了。

kmsg CLI封装为模型上下文协议（MCP），并使用macOS Accessibility API。 无需非正式API滚动 运行稳定。

免责条款：此工具旨在提高个人生产力。请遵守KakaoTalk使用条款并使用。因垃圾邮件、大量发送、自动刷屏等滥用而受到的账户制裁 本人责任是。我们都是大人了，相信您会看着办的。我没强迫你用！

主要功能

前提条件

• macOS （KakaoTalk桌面仅适用于macOS）
• 카카오톡 安装和登录桌面应用程序
• Python 3.8+ （包括默认的MacOS）
• 家酿 (安装)
• 克劳德代码 (安装)

安装

一键安装

git clone https://github.com/hadamyeedady12-dev/kmsg-mcp.git
cd kmsg-mcp
bash install.sh

手动安装

1. 安装kmsg

brew install channprj/tap/kmsg

1. 复制MCP服务器

mkdir -p ~/.local/share/kmsg-mcp
cp kmsg-mcp.py ~/.local/share/kmsg-mcp/
cp VERSION ~/.local/share/kmsg-mcp/

1. Claude Code MCP设置

~/.claude.json 在文件中添加以下内容：

{
  "mcpServers": {
    "kmsg": {
      "type": "stdio",
      "command": "python3",
      "args": ["-u", "~/.local/share/kmsg-mcp/kmsg-mcp.py"],
      "env": {
        "KMSG_BIN": "/opt/homebrew/bin/kmsg",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

KMSG_BIN 路径为 which kmsg可以通过确认。

1. 重新启动Claude Code

设置Accessibility权限

kmsg使用macOS Accessibility API控制KakaoTalk。必须授权终端应用程序：

1. 系统设置 > 隐私和安全 > 易于使用
2. 添加正在使用的终端应用程序（Terminal、iTerm2、Warp等）
3. 如果在IDE中使用Claude Code，还可以添加相应的IDE（VS Code、Cursor等）

使用方法

在Claude Code中使用自然语言即可：

# 메시지 읽기
"홍길동 카카오톡 메시지 읽어줘"
"개발팀 단톡방 최근 메시지 50개 보여줘"

# 메시지 보내기
"홍길동한테 카카오톡으로 '회의 시간 변경됐어' 보내줘"

# 이미지 보내기
"홍길동한테 ./screenshot.png 이미지 카카오톡으로 보내줘"

# 파일 보내기
"개발팀 단톡방에 ./report.pdf 파일 보내줘"

# 파일 다운로드
"홍길동 채팅방에서 파일 다운로드해줘"
"회장님 채팅방에서 '회의록.hwpx' 파일 다운로드해줘"

MCP工具详细信息

kmsg_read

参数类型必需说明 |----------|------|------|------| | chat |string|O|聊天室或用户名| | limit |integer|X|要读取的邮件数（1-100，默认值：20）| | deep_recovery |boolean|X|窗口恢复模式（默认为false）| | keep_window 保留自动打开的窗口（默认值：false） | trace_ax 包含|boolean|X|AX调试日志（默认值：false）|

kmsg_send

参数类型必需说明 |----------|------|------|------| | chat |string|O|聊天室或用户名| | message | string | O要发送的消息| | confirm 如果是|boolean|X|true，则发送前请求确认（默认为false）|

kmsg_send_image

参数类型必需说明 |----------|------|------|------| | chat |string|O|聊天室或用户名| | image_path |string|O|图像文件路径| | confirm 如果是|boolean|X|true，则发送前请求确认（默认为false）|

kmsg_send_file

参数类型必需说明 |----------|------|------|------| | chat |string|O|聊天室或用户名| | file_path |string|O|要发送的文件的绝对路径| | confirm 如果是|boolean|X|true，则发送前请求确认（默认为false）| | keep_window 保留自动打开的窗口（默认值：false）

kmsg_download_file

参数类型必需说明 |----------|------|------|------| | chat |string|O|聊天室或用户名| | filename 要下载的文件名（例如： 회의록.txt).跳过时的最近文件| | save_dir 存储目录（默认为： ~/Downloads) | | max_scroll |integer|X|浏览文件的最大滚动次数（0-20，默认值：5）| | icon_template_path 下载图标模板图像路径| | keep_window 保留自动打开的窗口（默认值：false）

filename如果指定，则向上滚动聊天室并浏览该文件。自动浏览屏幕上看不到的文件。

变更事项

v0.3.0（2026-04-23）

kmsg_send_file使实际运行稳定的发行版。

固定的

• kmsg_send_file 稳定剪贴板paste：macOS AppleScript keystroke "v" using command down无法稳定地到达KakaoTalk输入字段。用剪贴板+Quartz CGEvent鼠标点击+Quartz键盘事件组合重新配置。 (POSIX file 剪贴板→输入字段坐标AX lookup→Quartz click→Cmd+V→Return）
• AppleScript use 修正节位置错误: use framework "AppKit" 背脊 on run argv 后来osascript解析失败的错误（Korean MacOS error: "end"을(를) 예상했지만 "use"을(를) 발견했습니다）水晶。
• CGWindowID vs AppleScript window index混合错误修复: _get_kakao_window_id()返回的Quartz window number为AppleScript window N 修正了错误使用ordinal的问题（-10006错误）。
• 窗锁：window_id缓存，以便在下载流中，screenshot/scroll/click都在同一聊天窗口（非聊天列表的聊天窗口）上浮动。
• 暗模式韩文OCR匹配：将坐标转换为 retina_scale = image_width / window_bounds_width将其正则化为，以解决Retina显示屏上点击坐标偏移的问题。

添加

• send_file输入坐标LRU缓存：在同一聊天室中连续30秒内send_file切换坐标lookup（减少1秒的感受）。
• 粘贴失败时回退：Quartz路径失败时，使用osascript keystroke自动重试一次。
• 下载_文件AX 1차 + OCR回退：尝试在没有屏幕录制权限的环境中检测AX树中的附件row+保存按钮。
• 支持多个KakaoTalk窗口：英文/韩文区域设置（KakaoTalk / 카카오톡）全部识别。

改变

• 在send_file响应中 verified 删除字段。KakaoTalk的文件消息无正文地进入文本read API，验证逻辑总是返回false的问题（实际上正常到达时被报告为false）。将验证整理为不可选的可靠性提高方向（坐标准确度+retry）。

已知问题

• kmsg_download_file只有屏幕上显示的下载按钮row被定位为AX。屏幕上看不到的附件只能在授予macOS屏幕录制权限（System Settings→Privacy&Security→Screen Recording→Claude/终端激活）后通过OCR路径进行。
• KakaoTalk 1:1聊天室至少要发送一次信息并登记在聊天列表中才能被搜索（不能只搜索朋友列表）。

故障射击

“kmsg二进制文件不可执行”

kmsg未安装或不在PATH中。

brew install channprj/tap/kmsg
which kmsg  # 경로 확인

“访问权限被拒绝”

终端应用程序没有Accessibility权限。

系统设置>隐私和安全>易于使用在中添加终端应用程序。

“KakaoTalk窗口未就绪”

KakaoTalk未运行或处于最小化状态。

1. 请打开KakaoTalk登录
2. deep_recovery: true 请使用选项

“找不到聊天”

聊天室名称不正确。

• 请使用KakaoTalk上显示的正确名称
• 请注意空格
• 1:1聊天室的话，哪怕是一次对话，也要出现在聊天列表中。 搜索（仅注册朋友是不行的）

kmsg_send_file 回答ok:true，但未到达（v0.2.0以下）

在v0.3.0中修复。请升级。

kmsg_download_file “找不到文件或保存链接”

下载按钮必须显示在当前聊天窗口屏幕上才能显示为AX。在KakaoTalk上滚动到可以看到附件的位置，然后再次呼叫。

屏幕外附件自动滚动浏览在macOS上 屏幕录制权限需要（系统设置→隐私和安全→屏幕记录→Claude/添加终端后重新启动）。

环境变量

架构

Claude Code
  -> stdio -> kmsg-mcp.py (Python MCP 서버)
    -> subprocess -> kmsg (네이티브 바이너리)
      -> macOS Accessibility API
        -> KakaoTalk.app

• 纯Python标准库 -无需安装外部软件包
• MCP协议2024-11-05 遵守
• JSON-RPC 2.0 超过stdio

许可证

MIT许可证- 许可证 参考

信用