macos-screen-mcp

Give AI eyes on your macOS desktop.

Features

• Desktop awareness — frontmost app, visible apps, screen resolution
• Screenshot capture — full screen, specific region, or frontmost window
• Browser tab inspection — Chrome, Safari, and Arc support
• File preview — open files in default app, Chrome, or Quick Look

Requirements

• macOS 12 (Monterey) or later
• Node.js 18+
• Screen Recording permission (for screenshot features only)

Installation

Quick start (recommended)

claude mcp add --transport stdio macos-screen -- npx -y macos-screen-mcp

That's it. No global install needed.

Global install

npm install -g macos-screen-mcp
claude mcp add --transport stdio macos-screen -- macos-screen-mcp

From source

git clone https://github.com/dla-kirito/macos-screen-mcp.git
cd macos-screen-mcp
npm install && npm run build
claude mcp add --transport stdio macos-screen -- node /path/to/macos-screen-mcp/dist/index.js

Cursor / Other MCP Clients

Add to your MCP config:

{
  "mcpServers": {
    "macos-screen": {
      "command": "npx",
      "args": ["-y", "macos-screen-mcp"]
    }
  }
}

Permissions Setup

Screen Recording (required for screenshots)

The first time you use capture_screen, macOS will prompt for Screen Recording permission.

1. Open System Settings > Privacy & Security > Screen Recording
2. Enable the toggle for your terminal app (e.g., Ghostty, iTerm2, Terminal)
3. Restart your terminal if prompted

Automation (for browser tools)

The first time get_desktop_state or get_browser_content reads a browser's tabs, macOS will show a dialog like "<Terminal> wants to control "Google Chrome"". This is the standard macOS Automation prompt — click OK. macOS only asks once per app pair, and you can review/revoke it later under System Settings > Privacy & Security > Automation.

Note: preview_file doesn't require any special permissions — it uses the standard open command.

Available Tools

| Tool | Description | Permissions | |------|-------------|-------------| | get_desktop_state | Quick overview: frontmost app, visible apps, Chrome tabs, screen size | None | | capture_screen | Screenshot (full / region / frontmost window), returns as image | Screen Recording | | get_browser_content | Detailed browser tabs for Chrome, Safari, or Arc | None | | preview_file | Open a file in default app, Chrome, or Quick Look | None |

Security

• All tool inputs are validated via Zod schemas
• Application names are restricted to safe characters (no shell/AppleScript injection)
• File operations use execFile with argument arrays (no shell interpolation)

Privacy

This server runs locally and does not send data to any remote service of its own. However, by design it lets your AI assistant see parts of your desktop, and whatever the AI sees is sent to the LLM provider you've configured (Anthropic, your Cursor backend, etc.) as part of normal MCP tool responses.

What each tool exposes:

• get_desktop_state — frontmost app, list of visible apps, Chrome window URLs and titles, window positions, screen resolution
• get_browser_content — for the chosen browser: every window's active tab URL and title (and all tabs if include_all_tabs=true)
• capture_screen — raw pixels of your screen / a region / the frontmost window, sent as a base64 PNG
• preview_file — only opens the file locally; no file contents are read or transmitted by this server

Treat anything visible on screen or in a browser tab as something the AI may receive. Avoid calling these tools while password managers, private chats, banking sites, or other sensitive content are visible. Most MCP clients let you disable individual tools per session if you want a temporary lockdown.

Known Limitations

• macOS only — relies on AppleScript and macOS-specific commands
• Browser inspection requires the target browser to be running
• capture_screen requires explicit Screen Recording permission

License

MIT