For agents

Screenshots for your coding agent

Kestrel includes an MCP server over stdio. Your agent asks, Kestrel captures with its own Screen Recording permission, and you see a notification for every capture.

Turn it on

Agent access is off by default. Open Kestrel → Settings → General and enable Allow agents (MCP). The same pane offers one-click setup for every agent Kestrel finds.

Claude Code
Codex
Claude Desktop
Cursor
Windsurf
VS Code
Gemini CLI

~/projects/app

$ claude mcp add kestrel -- /Applications/Kestrel.app/Contents/MacOS/kestrel --mcp
Added stdio MCP server kestrel

> Why does the settings page look broken?

● kestrel · list_windows {"query":"Safari"}
  ⎿ 1 window · Safari · "Settings – Acme"
● kestrel · capture_window {"window":"Safari"}
  ⎿ image/png 1568 × 980

Captured the Safari window. The sidebar overlaps the form at 1280 pt, I will fix the grid.

Manual setup

Claude Code

$ claude mcp add kestrel -- /Applications/Kestrel.app/Contents/MacOS/kestrel --mcp

Other clients

Use this command and argument in any MCP client that speaks stdio:

/Applications/Kestrel.app/Contents/MacOS/kestrel --mcp

JSON config (Cursor, Claude Desktop, Windsurf …)

{
  "mcpServers": {
    "kestrel": {
      "command": "/Applications/Kestrel.app/Contents/MacOS/kestrel",
      "args": [
        "--mcp"
      ]
    }
  }
}

Tools

Images are scaled down to 1568 px on the long side. Pass maxSize to change that, or save: true to also keep the full-size file in your Kestrel folder.

Tool	What it does	Arguments
`list_displays`	Displays with id, position and size in points.	`–`
`list_windows`	Visible windows of other apps, front-most first: id, app, title, position, size.	`query`
`capture_screen`	Screenshot of a whole display.	`display, maxSize, save`
`capture_window`	Screenshot of one window, even if covered by others.	`window, shadow, maxSize, save`
`capture_active_window`	Screenshot of the front-most window of another app.	`maxSize, save`
`capture_area`	Screenshot of a rectangle in global points.	`x, y, width, height, maxSize, save`
`recognize_text`	On-device text and QR recognition of a window, display or rectangle.	`window, display, x, y, width, height`

How it stays safe

kestrel --mcp only relays to the running app, over a socket that only your user can open.
If Kestrel is not running, the bridge starts it.
Captures happen inside Kestrel, with Kestrel’s permission, not your terminal’s.
Turning off Allow agents makes every tool call fail with a clear message.

~/Library/Application Support/de.pixelandprocess.kestrel/mcp.sock