Plonk

io.github.ostapondoPublished by GitHub account ostapondov0.4.3Updated Oct 24, 2026

Plonk gives agents local macOS tools for windows, workspaces, screenshots, OCR, and more.

VerifiedSTDIODesktop onlyProductivity & WorkflowBrowser AutomationFiles & Storage

Overview

AI-generated overview

Lets an assistant control macOS windows, workspaces, screenshots, and on-screen text reading through the Plonk menu bar app.

What you can do
A thin stdio bridge to the Plonk macOS menu bar app. Tools cover window layout and snapping, saving and relaunching named workspaces, per-monitor snap zones, app window rules, keeping the Mac awake, taking and annotating screenshots, extracting on-screen text, measuring screen distances, choosing the active agent, and checking or installing updates.
When to use it
Useful on macOS when you want an assistant to arrange windows across monitors, restore a working desktop, capture or annotate the screen, or read text off the screen locally. It is desktop-only and adds nothing on other platforms.
Requirements
macOS 13+ with the Plonk menu bar app installed and running; Node.js 18+ to run the npm package plonk-mcp over stdio. Accessibility permission is required, and Screen Recording is requested separately on first capture. The app must run as the same user; no account or API key is needed.
Before you install
The server can move and resize windows, create, launch, and delete workspaces and zone sets, change app window rules, keep the Mac awake, capture the screen, and install app updates. Screenshots and extracted text are handled locally over loopback; the optional HTTP mode requires sending the contents of the Plonk token file as an X-Plonk-Token header.

Installation

In SourceWeft

  1. Open Plonk in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

plonk-mcp

The MCP server for Plonk, a macOS menu bar app that is eight utilities at once, a window manager among them. It lets an agent work the desk: apply layouts across monitors, save and relaunch workspaces, snap windows into zones, keep the screen awake, take and annotate screenshots, and read text off the screen without uploading a pixel.

browser on the left 60%, terminal top right, notes bottom right

save that as a workspace called "review"

screenshot the screen and tell me what looks off

This package is only half of it

plonk-mcp is a thin bridge. The app does the work, and without it every tool call returns "Plonk menu bar app is not running". Install it first — macOS 13+:

sh
brew install --cask ostapondo/plonk/plonk

Launch it, grant Accessibility when asked, and relaunch once so macOS picks the grant up. Screen Recording is asked for separately, the first time you capture.

Then point an agent at it

Node 18+.

sh
claude mcp add plonk -- npx -y plonk-mcp   # Claude Codecodex mcp add plonk -- npx -y plonk-mcp    # Codex CLI

Any MCP client works the same way — give it npx -y plonk-mcp as a stdio server. One-pagers for Cursor, Zed and Cline.

A client that cannot spawn a process connects over HTTP instead: npx -y plonk-mcp --http serves Streamable HTTP at http://127.0.0.1:43918/mcp (loopback only, --port to change). Requests to it carry the same token as the app's own API — send the contents of ~/Library/Application Support/Plonk/token as an X-Plonk-Token header. The stdio transport reads that file itself and needs no configuration.

Several clients may be connected at once. Set PLONK_AGENT_NAME in a client's config to tell two sessions of the same client apart.

Tools

get_stateMonitors, every open window and where it sits, zone sets, saved workspaces, awake status
apply_layout · snap_windowPlace windows by fraction of a screen, or drop one into a zone by number or by name
save_workspace · launch_workspace · delete_workspaceNamed desktops that reopen their apps and restore every window
save_zone_set · assign_zone_set · delete_zone_setSnap zones, assigned per monitor
set_app_rule · clear_app_ruleWhere an app's new windows open: a zone, and optionally a monitor
set_awakeKeep the Mac awake, optionally time-limited, optionally also holding your chat status at available
take_screenshot · annotate_screenshotCapture, mark up, hand the image back — mode: "app" photographs one named window even when it is buried, without raising it
extract_textRead the words off the screen, with a box per line in the same coordinates annotate_screenshot draws in
measure_screenHow far a point can travel each way before it meets an edge, or the distance between two points, in points and pixels
select_agentMake an agent the active one, optionally the only one allowed to control
check_for_update · install_updateAsk GitHub for a newer release and install it

save_layout, apply_saved_layout and delete_layout are older names kept for compatibility; they map onto the workspace tools.

Frames are fractions 0..1 of a monitor's visible area with the origin at the top left, so the left 60% is {x: 0, y: 0, w: 0.6, h: 1}.

Where things run

The server talks to the app over loopback HTTP on 127.0.0.1:43917 and nowhere else. No account, no cloud, no telemetry. It depends only on the official MCP SDK and zod.

The app gates that API on a token it writes to ~/Library/Application Support/Plonk/token. This server reads the file itself, so there is nothing to configure — but it does have to run as the same user Plonk is running as.

MIT. Source, screenshots and the rest of the documentation are in the repository.

Source: mcp/README.md at commit 55ffc7f

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

2
  1. v0.4.3LatestSep 22, 2026
  2. v0.4.1Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts