mcpField
P
plonk

plonk

Local
ostapondo.github.ioProductivity17Updated 5w ago
RepositoryVisit website

About plonk

plonk-mcp connects agents to the Plonk macOS menu bar app for window and workspace control, screen capture, and text extraction. It is for agents that need to inspect and arrange a local Mac desktop; the app must be installed and running.

Key features

  1. 01Arrange windows across monitors and zones
  2. 02Save and relaunch workspaces
  3. 03Capture and annotate screenshots
  4. 04Extract on-screen text with coordinates
  5. 05Keep the Mac awake
  6. 06Inspect monitor and window state

Use cases

  1. 01Arrange a desktop for a review session
  2. 02Restore a saved set of apps and windows
  3. 03Capture a window and inspect its contents
  4. 04Read visible text without uploading screen pixels

MCP support

Exposes Plonk app controls as MCP tools for agents, including window management, workspace operations, screenshots, OCR, and state queries. Supports stdio and loopback Streamable HTTP transports.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "ostapondo-plonk": {
      "command": "npx",
      "args": [
        "-y",
        "plonk-mcp"
      ]
    }
  }
}
Run commandnpx -y plonk-mcp

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npmplonk-mcp0.4.3

Tools

22

Saved tool list · updated 2w ago

This tool takes no parameters.

Details

From the project 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+:

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+.

claude mcp add plonk -- npx -y plonk-mcp   # Claude Code
codex 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.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.