Readshot MCP

Binary Path

The one-line macOS installer creates a readshot-mcp symlink in ~/.local/bin. Use readshot-mcp in configs when the host inherits that PATH. Desktop MCP hosts often do not, so the absolute app-bundle path is the more reliable default.

OS	Path
macOS	`/Applications/Readshot.app/Contents/MacOS/readshot-mcp`
Source build	`./target/release/readshot-mcp`

Tools

Tool	Use
`list_displays`	Return capturable displays.
`list_windows`	Return capturable app windows.
`capture_region`	Capture a display region and return a PNG payload.
`capture_window`	Capture a window, optionally with a window-relative region.
`capture_text`	Capture a region or window and return OCR text.
`capture_region_and_text`	Return both PNG pixels and OCR text.
`recent_captures`	Read recent captures from local history.
`latest_capture`	Return the newest saved capture.
`get_capture`	Return a saved capture by id.
`search_captures`	Search local history metadata and OCR text.

When display is omitted, the primary display is used. When rect is omitted, the selected display or window is captured in full.

Arguments

rect is always an object in logical pixels:

{ "x": 100, "y": 100, "width": 800, "height": 600 }

Region Capture

Argument	Notes
`display`	Display id from `list_displays`. Defaults to the primary display.
`rect`	Display-relative region. Defaults to the full display.
`scale`	Optional HiDPI scale override. Defaults to the display scale.
`hide_cursor`	Defaults to `true`. Set `false` to include the cursor when supported.

Window Capture

Argument	Notes
`window`	Required. Window id from `list_windows`.
`rect`	Window-relative region. Defaults to the full window.
`ignore_shadows`	Defaults to `false`. Set `true` for tighter captures when supported.

OCR and History

Argument	Notes
`languages`	Optional BCP-47 language hints. Omit for automatic language detection.
`language_correction`	Defaults to `true` where the platform OCR engine supports correction.
`limit`	Used by history list/search tools. Minimum 1, maximum 100.
`query`	Searches local history metadata and OCR text.

Host Config

Generate the standard JSON snippet from the CLI:

readshot mcp-config
readshot mcp-config --command /Applications/Readshot.app/Contents/MacOS/readshot-mcp

Check the MCP binary directly:

readshot-mcp --check

Terminal-launched hosts can usually use the short command:

{
  "mcpServers": {
    "readshot": {
      "command": "readshot-mcp"
    }
  }
}

For desktop apps, prefer the absolute path below unless you know the app inherits ~/.local/bin from your shell.

Claude Desktop

{
  "mcpServers": {
    "readshot": {
      "command": "/Applications/Readshot.app/Contents/MacOS/readshot-mcp"
    }
  }
}

Cursor

{
  "mcpServers": {
    "readshot": {
      "command": "/Applications/Readshot.app/Contents/MacOS/readshot-mcp",
      "type": "stdio"
    }
  }
}

OpenAI Desktop or Codex CLI

[mcp_servers.readshot]
command = "/Applications/Readshot.app/Contents/MacOS/readshot-mcp"

Continue.dev

{
  "mcpServers": [
    {
      "name": "readshot",
      "command": "/Applications/Readshot.app/Contents/MacOS/readshot-mcp"
    }
  ]
}

Tool Call Examples

Capture a region and return both pixels and OCR text:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "capture_region_and_text",
    "arguments": {
      "rect": { "x": 100, "y": 100, "width": 800, "height": 600 }
    }
  }
}

Capture a window:

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "capture_window",
    "arguments": {
      "window": "11474"
    }
  }
}

Capture text only:

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "capture_text",
    "arguments": {
      "rect": { "x": 100, "y": 100, "width": 800, "height": 600 }
    }
  }
}

Search local history:

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "search_captures",
    "arguments": {
      "query": "invoice",
      "limit": 10
    }
  }
}

Permissions

readshot-mcp does not prompt for Screen Recording itself. The host app that launches it, such as Claude Desktop or Cursor, needs Screen Recording permission in macOS System Settings.

Permission failures return a JSON-RPC error with code = -32001 and a message that the host can show to the user.

Verify

Set the binary path and ask the server for its advertised tools.

READSHOT_MCP=/Applications/Readshot.app/Contents/MacOS/readshot-mcp
"$READSHOT_MCP" --check

printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' \
  | "$READSHOT_MCP" \
  | python3 -m json.tool

List capturable windows:

printf '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_windows","arguments":{}}}\n' \
  | "$READSHOT_MCP" \
  | python3 -m json.tool

Troubleshooting

Symptom	Likely cause
`command not found`	The host is using the wrong binary path.
`code = -32001`	The host app lacks Screen Recording permission.
Empty display or window list	No capturable surface was available or permission was denied.
OCR returns empty text	The selected region is too small or contains no rendered text.