mcp-windowpeek

🤖 This code was written by a human-led AI agent.

An MCP server that allows AI agents to securely view open windows.

NOTE: Only MacOS is currently supported, but implementations for Linux and Windows can be trivally added later.

Tools

• list-windows — Lists visible windows that are in the allowlist, with their IDs, titles, and application names. If no allowlist is configured, returns an empty array.
• take-screenshot(window_id) — Captures a screenshot of the specified window and returns it as a base64-encoded PNG image directly in the tool result. No files are ever written to disk.

Platform Support

• macOS — Fully supported via CoreGraphics APIs.
• Windows — Stub implementation ready for a platform-specific backend.
• Linux — Stub implementation ready for a platform-specific backend.

macOS Screen Recording Permission

On macOS, the application running this server (e.g., Terminal, VS Code, or your agent harness) must have Screen Recording permission granted in System Settings > Privacy & Security > Screen Recording. Without it, take-screenshot will return an error.

Required: Allowlist Configuration

Window capture will not function until you explicitly configure an allowlist. This is a deliberate security measure: screenshots are inherently sensitive, and a compromised prompt or a maliciously crafted task could attempt to autonomously capture and exfiltrate private information. Rather than maintaining a partially-effective blocklist, mcp-windowpeek requires you to explicitly declare which applications the agent is permitted to capture.

How to configure

Add an --allowlist argument to your MCP server config, containing a comma-separated list of application names exactly as they appear in list-windows:

{
  "mcpServers": {
    "windowpeek": {
      "command": "/path/to/mcp-windowpeek",
      "args": ["--allowlist", "Sublime Text,Zed,Ghostty"]
    }
  }
}

If no allowlist is provided, both tools are effectively disabled: list-windows returns an empty array and take-screenshot returns an error instructing the agent to ask you (the user) to configure one.

Optional: Rate limiting

When an allowlist is present, a sensible rate limit (10 screenshots per minute, with a minimum 2-second gap between any two screenshots) is applied automatically.

You can override the per-minute cap with --rate-limit N, where N is screenshots per minute. For example, --rate-limit 20 allows up to 20 screenshots per minute (the 2-second gap still applies):

{
  "mcpServers": {
    "windowpeek": {
      "command": "/path/to/mcp-windowpeek",
      "args": ["--allowlist", "Zed", "--rate-limit", "20"]
    }
  }
}

Optional: Resolution control

By default, screenshots are downscaled so their width does not exceed 1600 px. You can override this with --max-width:

{
  "mcpServers": {
    "windowpeek": {
      "command": "/path/to/mcp-windowpeek",
      "args": ["--max-width", "1280", "--allowlist", "Zed"]
    }
  }
}

Configuration via environment variables

Each CLI flag has a corresponding environment variable that takes priority over the flag. This is useful for one-off overrides without editing your MCP harness configuration:

Flag	Environment variable
--allowlist	WINDOWPEEK_ALLOWLIST
--rate-limit	WINDOWPEEK_RATE_LIMIT
--max-width	WINDOWPEEK_MAX_WIDTH

{
  "mcpServers": {
    "windowpeek": {
      "command": "/path/to/mcp-windowpeek",
      "args": ["--allowlist", "Zed"],
      "env": {
        "WINDOWPEEK_ALLOWLIST": "Zed,Ghostty"
      }
    }
  }
}

In the example above, WINDOWPEEK_ALLOWLIST wins and the allowlist is Zed,Ghostty.

Audit log

Every successful screenshot is logged to a file in the system temp directory (mcp-windowpeek-audit.log). Each line contains a Unix timestamp, the application name, and the window title, so you can review exactly what the agent has seen.

Building

cargo build --release

The release binary will be at target/release/mcp-windowpeek.