Skip to content
Agentmart
Submit a tool

Plonk

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

Connector by ostapondo · GitHub account verified by the MCP Registry

IndexedMITLocal (stdio)★ 17
Write a review

Install

Works with Claude Code, Codex, VS Code, Cursor, Windsurf, Claude Desktop. Read the repository before you give any tool access to your data.

npx agentmarket install connector/ostapondo-plonk

Asks which of your tools to add it to (Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, Claude Desktop) and shows the change first. See https://agentmart.dev/cli.

Get the weekly diff

The weekly diff: one email a week with new agent tools, notable updates and grade changes, plus security alerts for tools you follow. Double opt-in, one-click unsubscribe.

We use your email only for this newsletter. Privacy

About

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

Reviews

Write a review

No reviews yet. Installed it? Reviews come from verified installers only. How reviews work

Permissions

What this server can do and what it asks for, from its tool list, install config and code. Checked Oct 26, 2026.

Tools
6 read · 10 write · 5 delete · 1 not yet classified
Secrets
None asked for
Install scripts
None found
Runs as
Node.js package

Tools by what they do 22

Read from the source code; the running server may list different tools.

Read 6 · Look things up without changing anything.

  • annotate_screenshot
  • check_for_update
  • extract_text
  • get_state
  • measure_screen
  • take_screenshot

Write 10 · Create, change, send or run things.

  • apply_layout
  • apply_saved_layout
  • assign_zone_set
  • install_update
  • save_layout
  • save_workspace
  • save_zone_set
  • select_agent
  • set_app_rule
  • set_awake

Delete 5 · Delete, drop, revoke or wipe things.

  • clear_app_rule
  • delete_layout
  • delete_workspace
  • delete_zone_set
  • snap_window

Not yet classified 1 · We could not tell from the name and description.

  • launch_workspace

Network hosts it talks to 2

  • github.com · found in code
  • ostapondo.github.io · found in code

Files it touches

  • Your home directory (~)
  • Any path the agent passes to its tools

Tools (22)

Read from the source code; the running server may differ. Descriptions are the server’s own words; hidden characters are shown as [U+…].

  • annotate_screenshot

    Draw on a screenshot you already took, then copy it to the clipboard and show it to the user. Call take_screenshot first and LOOK at the image: you cannot know where anything is until you have seen it. Points are fractions 0..1 of the image, origin TOP-LEFT, so a rectangle around a left sidebar that is a seventh of the width and starts under the title bar is [{x:0,y:0.05},{x:0.14,y:1}]. Rectangle and ellipse take two opposite corners, arrow takes start then tip, pen and highlight take a run of points. Returns the marked image so you can check what you drew.

  • apply_layout

    Move and resize windows to build a layout. Each item places one window: 'app' is the app name (fuzzy matched), optional 'title' filters windows of that app by title substring, optional 'screen' is the monitor index from get_state (each monitor can get its own layout — just send items with different 'screen' values; defaults to the screen the window is currently on), 'frame' is {x,y,w,h} as fractions 0..1 of that screen's visible area with origin at TOP-LEFT (left half = {x:0,y:0,w:0.5,h:1}; bottom-right quarter = {x:0.5,y:0.5,w:0.5,h:0.5}; centered 60% = {x:0.2,y:0.15,w:0.6,h:0.7}). Windows ar…

  • apply_saved_layout

    Launch a saved workspace by name. Legacy name kept for older clients — new integrations should call launch_workspace, which adds a 'screen' option to pull the whole workspace onto one monitor. Opens every app that is not running, waits for its windows, and moves them into the saved positions; macOS cannot open an app straight into a position, so windows appear first and jump into place. Returns per-app success and reports apps that never opened a window. Takes up to a minute for a large workspace.

  • assign_zone_set

    Assign a zone set (built-in or saved) to one monitor, so dragging a window there snaps to that set's zones. Each monitor keeps its own assignment; assigning replaces whatever that monitor used before and takes effect on the next drag. Omit 'name' to restore the default set (Halves); pass 'edge' for plain edge snapping instead of zones. Available set names and current per-monitor assignments are in get_state.

  • check_for_update

    Ask Plonk whether a newer release exists, and report what is installed. Use this when the user asks what version they run, whether Plonk is up to date, or before calling install_update — which refuses unless a newer release is already on offer. The check is a network round trip to the GitHub releases API, so this returns immediately with the state as it stands and the result lands a moment later: read it back from get_state's 'update' key, or wait for an 'update' event on the change stream. If the user has turned update checks off, this fails with 409 rather than dialling out on their behalf —…

  • clear_app_rule

    Remove the rule set for an app with set_app_rule, so its new windows open wherever the app puts them again, or where its last window went when that habit is switched on in Plonk. 'app' is the pattern exactly as get_state.app_rules lists it, ignoring case. Fails when no rule matches; nothing else changes.

  • delete_layout

    Delete the saved workspace with that name, whether it was saved with save_layout or save_workspace. Legacy name kept for older clients — new integrations should call delete_workspace, which does the same. Use it to clean up saved workspaces that are no longer wanted; existing names are listed in get_state.

  • delete_workspace

    Delete a saved workspace by name. Use this to clean up workspaces you created that are no longer wanted.

  • delete_zone_set

    Delete a saved zone set by name. Any monitor currently using it falls back to the default set (Halves), so snapping keeps working. Only sets made with save_zone_set can go: the built-ins (Halves, Thirds, 60 / 40, Quarters, Priority) are refused. Deleting is immediate and cannot be undone — the zones would have to be described again. Saved sets and their per-monitor assignments are listed in get_state; use assign_zone_set instead when a monitor should merely stop using a set that others still need.

  • extract_text

    Read the words off the screen, or off a saved image, and return them as text. Recognition runs on the Mac itself and nothing is uploaded. Prefer this over take_screenshot whenever the answer is words rather than a picture — an error dialog, a log, a terminal, a table, text baked into an image or a paused video, a PDF page in a viewer that will not let text be selected. It costs a fraction of the tokens an image does and does not depend on reading pixels correctly. Use take_screenshot instead when layout, colour or 'what does this look like' is the question. mode 'screen' captures everything wi…

  • get_state

    Get the current desktop state: all screens/monitors (index, frame, visible area — coordinates have origin at top-left of the primary screen, y grows down), all open windows (app name, title, which screen it is on, absolute frame, and 'fraction' — its position as fractions 0..1 of that screen's visible area), 'zone_sets' (every set by name, each zone as {x,y,w,h} with a 'name' where the set gives it one), 'screen_zone_sets' (which set each monitor wears), saved layout names, 'app_rules' (where each app's new windows open, see set_app_rule), 'place_new_windows' and 'auto_fill_zones', whether a k…

  • install_update

    Install the release that check_for_update found: Plonk downloads the build, checks it is signed with the same certificate as the running copy, swaps the bundle in, and relaunches itself. Prefer this over telling the user to download a build by hand — the signature check is also what preserves their Accessibility and Screen Recording grants, which a hand-installed copy can lose. Ask the user before calling it: it quits the app, so any window arrangement in flight stops and the local API is unreachable for a few seconds until the new copy is up. It fails without touching the installed copy when …

  • launch_workspace

    Launch a saved workspace: opens every app that is not running, waits for its windows, and moves them into the saved positions. Each window returns to the monitor it was captured on, so a workspace spanning several displays comes back spanning them. macOS cannot open an app straight into a position, so windows appear first and jump into place. Returns per-app success, and reports apps that never opened a window. Takes up to a minute for a large workspace.

  • measure_screen

    Measure the screen in points and pixels, without taking a picture of it. Plonk photographs the screen once and walks out from the given point in all four directions until one pixel is unlike the one before it, which is where an edge is. What comes back is how far the point could travel each way: the run across and the run down. Prefer this over take_screenshot whenever the answer is a number: how wide that sidebar is, how tall that row is, how big the gap between two things is, is that tap target 44 points. An image costs far more tokens and still has to be eyeballed. Use extract_text when the…

  • save_layout

    Save the named window arrangement as a workspace. Legacy name kept for older clients — new integrations should call save_workspace, which can also record whether running apps get moved into place. Omit 'items' to snapshot the windows exactly as they are on screen right now; pass 'items' to describe the arrangement explicitly. Saving over an existing name replaces it. Saved workspaces are listed in get_state, with their full contents.

Show 7 more tools
  • save_workspace

    Save a workspace: the apps of a desktop setup, where each window goes, and what each app should open. Pass 'items' to describe the arrangement, or omit them to snapshot the windows exactly as they are on screen right now. Saving over an existing name replaces it. Saved workspaces are listed in get_state, with their full contents.

  • save_zone_set

    Create or replace a named zone set used for drag snapping. Zones are rectangles {x,y,w,h} as fractions 0..1 of a screen's visible area, origin TOP-LEFT; each zone must stay inside the screen, but zones may overlap each other (the smallest one under the cursor wins). A zone may also carry a 'name' ('chat', 'editor'): it is drawn under the zone's number, the user can say it out loud, and snap_window takes it instead of the number; names must be unique within the set, ignoring case, and cannot be a bare number. Pass 'screen' to also assign the set to that monitor so it becomes active immediately.…

  • select_agent

    Make an agent the user's active one in Plonk. Omit 'name' to select this client itself; pass "" to clear the choice so any agent may drive. The active agent shows in Plonk's menu bar and settings, and is where voice and other outgoing requests will go. With 'exclusive' true the app also rejects window and settings changes from every other agent (they can still read state and take screenshots). Connected agents are listed in get_state under 'agents'.

  • set_app_rule

    Make an app's windows open into a numbered zone from now on, so an arrangement holds without anyone dragging: 'Slack always in zone 1 on the second monitor'. 'app' is matched anywhere in the app's name or bundle id, case-insensitively, the way get_state.excluded_apps entries are; a bundle id such as 'com.tinyspeck.slackmacgap' is the safest form. 'zone' is the number Plonk draws on the zone (1-based) in the set assigned to that monitor. 'screen' is a monitor index from get_state and is stored as that display's identity, so it survives a reboot renumbering the screens; omit it and the window st…

  • set_awake

    Keep the Mac from sleeping, and optionally keep the user shown as available in chat apps. One session with two levels, called Pulse in the app. 'available' picks the level. Left off, Plonk holds a power assertion: the Mac does not sleep, but Slack and Teams still slide the user to Away, because those read the system idle timer and an assertion does not touch it. Turned on, Plonk also resets that idle timer with a Shift keypress every two minutes, which is what keeps a chat status green — and which postpones sleep by itself, so being available always includes being awake. Use it whenever the po…

  • snap_window

    Drop one window into a zone of the snap-zone set assigned to that monitor, by number or by name. The numbers are the ones Plonk draws on the zones while a window is dragged, so 'the middle zone' of a three-zone set is 2; a name is whatever the set calls a zone ('chat'), listed per zone in get_state.zone_sets, matched ignoring case. Fails with the zones that screen does have, names included, when neither matches. Zone sets and their per-monitor assignment are in get_state; use apply_layout instead when the user describes a size rather than a zone.

  • take_screenshot

    Capture the screen and return the image so it can be looked at. mode 'screen' captures everything (no user interaction); mode 'app' captures one named window and needs no user interaction either — pass 'app' and/or 'title_contains', and it works even when that window is behind others, minimized excepted, without raising it or taking focus; 'region' and 'window' hand the user the native crosshair/window picker and wait for them. Prefer 'app' whenever the user asks about a particular program ("what is playing in Spotify", "read the error in Xcode") — it is the only mode that can see a window the…

Signals

Stars
17
Forks
2
Open issues
14
Last commit (this folder)
Sep 22, 2026 (1 month ago)
Last release
Sep 22, 2026 (1 month ago)

From GitHub (fetched Oct 24, 2026).

Details

Registry name
io.github.ostapondo/plonk
Version
0.4.3
Auth
No auth
Packages
npm plonk-mcp
License
MIT
Repository
github.com/ostapondo/plonk
Website
ostapondo.github.io/Plonk/
First seen
Oct 24, 2026
Last checked
Oct 24, 2026
Source
Official MCP Registrygithub-graphql
Cite this page

Plonk MCP server. Agent Mart. https://agentmart.dev/connectors/ostapondo-plonk (last updated 2026-10-24)