peek logo peek

Support

Need help? Start here.

Get help

System requirements

  • macOS 14 Sonoma or later.
  • Apple Silicon or Intel.
  • Screen Recording permission (granted once on first capture).
  • An MCP client that speaks streamable-HTTP MCP (Claude Code, Cursor, etc.) to use the agent path. The click-to-clipboard menu works without any client.

Connecting your MCP client

Open peek → menu bar icon → Settings… → MCP tab. There are two Copy Config buttons:

Claude Code / Cursor / streamable-HTTP clients

Copy Claude Code config emits the loopback URL directly:

{
  "mcpServers": {
    "peek": {
      "url": "http://127.0.0.1:11474",
      "headers": {
        "Authorization": "Bearer <your token>"
      }
    }
  }
}

Claude Desktop

Claude Desktop’s claude_desktop_config.json only accepts the stdio transport. Copy Claude Desktop config emits a snippet that wraps the bearer in a pinned mcp-remote bridge fetched via npx — Node.js must be installed.

{
  "mcpServers": {
    "peek": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote@0.1.38",
        "http://127.0.0.1:11474/",
        "--allow-http", "--transport", "http-only",
        "--header", "Authorization: Bearer <your token>"
      ]
    }
  }
}

Paste the relevant snippet into your client’s MCP config, restart. Then use peek’s Test connection button in Settings to confirm the listener is responding before you involve the client.

Frequently asked questions

Why does peek need Screen Recording permission?

ScreenCaptureKit requires Screen Recording (TCC) to enumerate windows and produce captures. Without it the system returns empty content. Window titles in list_windows also require this permission, so peek would have to ask for it either way. peek itself never raises, moves, or focuses windows — the permission is purely for reading pixels.

Why HTTP MCP and not stdio?

A stdio MCP server runs as a child process of the MCP client. Under macOS App Sandbox a child process gets its own sandbox container and cannot inherit the parent’s Screen Recording grant. Going HTTP-first lets the long-running peek menu bar app own the TCC grant once and serve every MCP client over a single loopback endpoint.

I see “No captureable windows” in peek’s menu — why?

Almost always Screen Recording permission. Open System Settings → Privacy & Security → Screen Recording and confirm peek is enabled. If the menu bar icon is the slashed-viewfinder variant, the menu also exposes a Grant Screen Recording… shortcut that deep-links to the right pane. After granting, fully quit and relaunch peek so the granted state is picked up.

How do I rotate the MCP bearer token?

Settings → MCP → Bearer Token → Rotate token. This invalidates the old token in the Keychain and generates a new one. Re-copy whichever Copy Config snippet your client uses and paste it into the client’s MCP config — the URL stays the same, only the Authorization header changes. Restart the client.

Will peek work with Claude Desktop?

Yes. Peek ships a pinned mcp-remote bridge config alongside the native streamable-HTTP one. In Settings → MCP, click Copy Claude Desktop config: it copies a stdio-transport snippet that wraps the bearer auth in an npx -y mcp-remote@… command. Paste into ~/Library/Application Support/Claude/claude_desktop_config.json, restart Claude Desktop, and the three peek tools appear. Node.js must be installed.

How do I deploy this in an organisation?

peek reads managed preferences from /Library/Managed Preferences/com.oldsalt.peek.plist. In JAMF Pro: Computers → Configuration Profiles → new profile → Application & Custom Settings, with preference domain com.oldsalt.peek. Other MDMs follow the same pattern. Full key reference in the README.

I’m an admin and a setting won’t change in the UI.

Settings under managed-preferences control display a lock icon and are intentionally non-editable from the user’s settings window. The “Managed by Organisation” section lists which constraints are active. To change them, update the configuration profile in your MDM.

Does peek send any data to the developer?

No. The app makes no outbound network requests. See the privacy policy.

Where can I see the source code?

github.com/just-an-oldsalt/peek. The app is MIT licensed.

Reporting a bug

The fastest path is a GitHub issue with: your macOS version, the peek version (visible from the menu bar → Settings), what you expected to happen, what actually happened, and (if relevant) the contents of any managed preferences plist applied to your machine. For MCP-specific issues, the output of Test connection in peek’s menu and the response from your MCP client’s tool list are usually the most useful artefacts.