plonk

plonk-mcp

Plonk 用の MCP サーバーです。Plonk は、ウィンドウマネージャーを含む 8 つのユーティリティを兼ねる macOS メニューバーアプリです。エージェントがデスクトップを操作できるようにします。複数のモニターにまたがるレイアウトの適用、ワークスペースの保存と再起動、ウィンドウのゾーンへのスナップ、画面のスリープ防止、スクリーンショットの撮影と注釈の追加、ピクセルをアップロードせずに画面上のテキストを読み取ることができます。

ブラウザーを左側の 60% に、ターミナルを右上に、メモを右下に配置して

「review」という名前のワークスペースとして保存して

画面のスクリーンショットを撮って、問題がありそうな箇所を教えて

このパッケージだけでは機能の半分しか使えません

plonk-mcp は薄いブリッジです。実際の処理はアプリが行います。アプリがないと、すべてのツール呼び出しで「Plonk menu bar app is not running」が返されます。先に macOS 13 以降にインストールしてください。

brew install --cask ostapondo/plonk/plonk

起動し、求められたらアクセシビリティの許可を付与してから、macOS に許可を認識させるために一度再起動してください。画面収録の許可は、初めてキャプチャするときに別途求められます。

次に、エージェントから接続します

Node 18 以降が必要です。

claude mcp add plonk -- npx -y plonk-mcp   # Claude Code
codex mcp add plonk -- npx -y plonk-mcp    # Codex CLI

どの MCP クライアントでも同じように動作します。stdio サーバーとして npx -y plonk-mcp を指定してください。 Cursor、 Zed、 Cline 向けのガイドもあります。

プロセスを起動できないクライアントは、代わりに HTTP で接続します。 npx -y plonk-mcp --http は http://127.0.0.1:43918/mcp で Streamable HTTP を提供します（ループバックのみ。変更するには --port を指定）。リクエストにはアプリ独自の API と同じトークンを含めます。~/Library/Application Support/Plonk/token の内容を X-Plonk-Token ヘッダーとして送信してください。 stdio トランスポートはこのファイルを自動で読み込むため、設定は不要です。

複数のクライアントを同時に接続できます。同じクライアントの 2 つのセッションを区別するには、クライアントの設定で PLONK_AGENT_NAME を指定してください。

ツール

get_state	モニター、開いているすべてのウィンドウとその位置、ゾーンセット、保存済みワークスペース、スリープ状態
apply_layout · snap_window	画面に対する比率でウィンドウを配置するか、番号または名前で指定したゾーンにウィンドウを配置
save_workspace · launch_workspace · delete_workspace	アプリを再び開き、すべてのウィンドウを復元する名前付きデスクトップ
save_zone_set · assign_zone_set · delete_zone_set	モニターごとに割り当てるスナップゾーン
set_app_rule · clear_app_rule	アプリの新しいウィンドウを開く場所を設定。ゾーンと、必要に応じてモニターを指定
set_awake	Mac のスリープを防止。時間制限を設定でき、チャットのステータスを「対応可能」に保つこともできます
take_screenshot · annotate_screenshot	キャプチャして注釈を付け、画像を返します。mode: "app" では、背後に隠れていても、前面に移動させずに名前で指定したウィンドウを撮影できます
extract_text	画面上のテキストを読み取ります。各行に付くボックスの座標は、annotate_screenshot が描画する座標と同じです
measure_screen	点が各方向に端まで移動できる距離、または 2 点間の距離を、ポイントとピクセルで測定
select_agent	エージェントをアクティブにします。必要に応じて、制御できるエージェントをそのエージェントのみに制限できます
check_for_update · install_update	GitHub に新しいリリースがあるか確認し、インストール

save_layout、apply_saved_layout、delete_layout は、互換性のために残されている旧名称です。これらはワークスペース用ツールに対応しています。

フレームはモニターの表示領域に対する 0..1 の比率で表し、原点は左上です。そのため、左側の 60% は {x: 0, y: 0, w: 0.6, h: 1} となります。

実行場所

サーバーはループバック HTTP を介して 127.0.0.1:43917 でアプリと通信し、それ以外の場所とは通信しません。アカウント、クラウド、テレメトリーは不要です。依存するのは公式 MCP SDK と zod のみです。

アプリは、自身が ~/Library/Application Support/Plonk/token に書き込むトークンによって API へのアクセスを制御します。このサーバーはファイルを自動で読み込むため、設定は不要です。ただし、Plonk と同じユーザーで実行する必要があります。

MIT ライセンスです。ソース、スクリーンショット、その他のドキュメントはリポジトリにあります。