plonk — Claude Code MCP server: what it does, how to install
Gives AI agents tools to manage macOS windows, trigger local OCR, grab screenshots, and save workspaces. Requires the Plonk menu bar app.
claude mcp add plonk -- npx -y plonk-mcpWhat plonk does
The plonk-mcp package operates as a bridge to the Plonk menu bar tool on macOS 13 or newer. Every tool call fails if the companion app is not already running. Running the server requires Node 18+, while the desktop binary installs via brew install --cask ostapondo/plonk/plonk.
Once connected, agents inspect monitors via get_state, position windows using monitor fractions from 0 to 1, or snap apps into designated zones. The extract_text tool parses screen text locally, avoiding image uploads. Agents can also capture hidden application windows directly through take_screenshot.
All traffic stays on loopback at 127.0.0.1:43917 without telemetry. The server reads the security secret from ~/Library/Application Support/Plonk/token automatically. Because of this, both Plonk and your MCP client must run under the same macOS user account.
What it helps with
- arrange windows across displays using coordinate fractions
- save and restore application workspaces
- capture screenshots of occluded windows without raising them
- extract on-screen text with bounding boxes locally
- prevent macOS from sleeping during long tasks
Example prompts for the agent
- Place the browser on the left 60% of the screen and terminal on the right
- Save the current window layout as a workspace named review
- Take a screenshot of the main monitor and check for UI glitches
How to install plonk
Platform CLI
claude mcp add plonk -- npx -y plonk-mcpPlatform CLI
codex mcp add mcp -- npx -y plonk-mcpConfig file
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"plonk-mcp"
]
}
}
}Config file
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"plonk-mcp"
]
}
}
}Platform CLI
gemini mcp add mcp npx -y plonk-mcpStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about plonk
How to install plonk in Claude Code?
Install the desktop app with brew install --cask ostapondo/plonk/plonk and launch it. Then register the MCP server by running claude mcp add plonk -- npx -y plonk-mcp.
What does plonk do?
It lets your agent control macOS window placement, manage multi-monitor zone sets, and take screenshots. It also runs local text extraction on visible windows through an offline loopback connection.
Why does plonk return an error about the menu bar app?
The MCP server is only a bridge and cannot control windows on its own. The Plonk macOS app must be active under the same user account with Accessibility and Screen Recording permissions enabled.
