kmsgの使い方
インストール、主要コマンド、安全な読み取り、JSON、MCP、トラブルシューティングを説明します。
このページでは、インストールからメッセージの読み取り・送信、MCPサーバー、トラブルシューティングまでの主要な操作を説明します。全オプションは英語版リファレンスで確認できます。
インストール
必要な環境
- macOS 13以降
- macOS版KakaoTalk
- 実際に実行する
kmsgバイナリへのアクセシビリティ権限
Homebrew
brew install channprj/tap/kmsg
アップデート:
kmsg update
kmsg updateは必要に応じてHomebrewをインストールし、フォーミュラをインストールまたはアップグレードし、直接インストールしたバイナリをHomebrew管理のコマンドにリンクします。
ソースからビルド
git clone https://github.com/channprj/kmsg.git
cd kmsg
swift build -c release
install -m 755 .build/release/kmsg ~/.local/bin/kmsg
クイックスタート
最初に権限とKakaoTalkの状態を確認します。
kmsg status --verbose
チャット一覧を取得し、最近のメッセージを読みます。
kmsg chats --limit 20
kmsg read "チャット名" --limit 20
送信前に対象と内容を確認します。
kmsg send "チャット名" "こんにちは" --dry-run
--dry-runはKakaoTalk UIへアクセスする前に終了するため、メッセージを送信しません。
ログインと権限
kmsg auth login
kmsg auth login --auto
パスワードはAES-GCMで暗号化され、認証情報と鍵は所有者だけが読める別々のファイルに保存されます。これらのファイルを公開しないでください。
~/.config/kmsg/credentials.json
~/.config/kmsg/credentials/primary.key
ロックモード
KakaoTalkのロック画面が表示されている場合は、コマンドの実行前にロックを解除し、元の要求をそのまま続行します。
パスワードは保存済みの値から取得します。前回の解除で記憶したロックパスワードを優先し、無ければkmsg auth loginで保存したアカウントのパスワードを使います。どちらも無い場合のみ入力を求め、成功した値を記憶します。
ロック解除はコマンドごとに一度だけ試行します。パスワードを何度も間違えるとKakaoTalkがアカウントをログアウトさせるためです。保存済みのアカウントパスワードが拒否された場合は再試行しないので、kmsg auth loginで現在のパスワードを保存してください。
ターミナルを持たない呼び出し元（kmsg mcp-server、kmsg watch、cron）は入力を受け取れないため、保存済みの認証情報に依存します。
コマンド一覧
| コマンド | 用途 |
|---|---|
kmsg status |
権限、KakaoTalk、ログイン、準備状態を確認 |
kmsg auth login |
認証情報を入力または再利用 |
kmsg chats |
チャット一覧とローカルchat_idを取得 |
kmsg read |
最近のメッセージを読み取る |
kmsg watch |
新着メッセージを継続監視 |
kmsg send |
テキストメッセージを送信 |
kmsg send-image |
画像を送信 |
kmsg inspect |
AX階層を調査 |
kmsg cache |
AXパスキャッシュを管理 |
kmsg mcp-server |
ネイティブstdio MCPサーバーを起動 |
kmsg update |
Homebrewのリリースへkmsgを更新 |
安全な読み取り
前面での作業を妨げたくない場合は--background-safeを使います。
kmsg read "チャット名" --json --background-safe
このモードはKakaoTalkの起動・アクティブ化・ログイン・検索・ウィンドウ操作を行いません。対象のチャットウィンドウがすでに表示されていなければ失敗します。
--background-safeが表示されない場合
このCLIフラグはkmsg v1.260618.0以降で提供され、kmsg readコマンドでのみ使用できます。現在のシェルが実行するバイナリを確認してください。
kmsg --version
kmsg read --help
ヘルプにフラグが表示されない場合は、Homebrew版を更新して再確認します。
brew update
brew upgrade kmsg
kmsg read --help
MCPクライアントでは、CLI表記の--background-safeではなくJSON引数background_safe: trueを使用します。
送信
kmsg send <recipient> <message> [options]
kmsg send --chat-id <chat-id> <message> [options]
| オプション | 動作 |
|---|---|
--dry-run |
UIを操作せず、対象と内容だけを表示 |
--chat-id ID |
kmsg chatsが生成したローカルIDを利用 |
--keep-window |
コマンドが開いたチャットを維持 |
--no-cache |
関連AXキャッシュを破棄して再探索 |
--layout MODE |
ウィンドウ配置を指定 |
画像送信:
kmsg send-image "チャット名" /absolute/path/image.png --dry-run
JSONとMCP
kmsg chats --json
kmsg read "チャット名" --json
kmsg watch "チャット名" --json
構造化結果はstdout、AX診断はstderrに出力されます。
MCPサーバーは次のツールを公開します。
| ツール | 用途 |
|---|---|
kmsg_read |
最近のメッセージを読み取る |
kmsg_send |
テキストを送信 |
kmsg_send_image |
ローカル画像を送信 |
送信ツールでは、confirm=trueは送信せずCONFIRMATION_REQUIREDを返します。confirm=falseまたは省略時は即時送信です。
主な環境変数
| 変数 | 既定値 | 説明 |
|---|---|---|
KMSG_MCP_KMSG_PATH |
現在の実行ファイル | MCPサーバーが呼び出すパス |
KMSG_MCP_TIMEOUT_SECONDS |
30 |
サブプロセスの制限時間 |
KMSG_DEFAULT_LAYOUT |
preserve |
既定のウィンドウ配置 |
KMSG_DEFAULT_BACKGROUND_SAFE |
false |
安全な読み取りの既定値 |
KMSG_DEFAULT_DEEP_RECOVERY |
false |
深い復旧の既定値 |
トラブルシューティング
アクセシビリティ権限がない
kmsg status
システム設定で、実際に実行しているバイナリを許可します。Homebrew版とローカルビルドは別のバイナリとして扱われる場合があります。
チャットが見つからない
kmsg chats --verbose --limit 50
kmsg cache clear
kmsg read "正確なチャット名" --deep-recovery
繰り返し実行する自動化では、kmsg chatsでレジストリを更新しchat_idを利用すると安定します。
UI構造が変わった
kmsg read "チャット名" --debug --trace-ax
kmsg inspect --depth 5
kmsg cache stats
KakaoTalk更新後はキャッシュを消去して再探索してください。