# macos-screen-mcp

[![npm version](https://img.shields.io/npm/v/macos-screen-mcp)](https://www.npmjs.com/package/macos-screen-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
![macOS](https://img.shields.io/badge/platform-macOS-blue)
![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)

Give AI eyes on your macOS desktop — an [MCP](https://modelcontextprotocol.io/) server that lets AI assistants see your screen, read browser tabs, and capture screenshots.

## Features

- **Desktop awareness** — frontmost app, visible apps, window positions, screen resolution
- **Screenshot capture** — full screen, specific region, or frontmost window (with configurable scale)
- **Browser tab inspection** — Chrome, Safari, and Arc support (active tab or all tabs)
- **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)

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

That's it. No global install needed.

### Global install

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

### From source

```bash
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:

```json
{
  "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 |

### Tool Details

**`capture_screen`** supports a `scale` parameter (0–1, default 0.5) to reduce image size before sending to the LLM, saving tokens while preserving enough detail for most tasks.

**`get_browser_content`** can return just the active tab per window (default) or all tabs with `include_all_tabs: true`.

## How It Works

The server communicates with AI clients over **stdio** using the [Model Context Protocol](https://modelcontextprotocol.io/). Under the hood it uses:

- **AppleScript** (`osascript`) to query desktop state, window bounds, and browser tabs
- **`screencapture`** (macOS built-in) to take screenshots
- **`sips`** to downscale images before returning them as base64 PNG

All operations are **read-only** — the server never modifies your files, settings, or browser state.

```
┌─────────────┐   stdio/MCP   ┌──────────────────┐   AppleScript   ┌─────────┐
│  AI Client   │◄────────────►│  macos-screen-mcp │◄──────────────►│  macOS   │
│ (Claude etc) │              └──────────────────┘   screencapture  │ Desktop  │
└─────────────┘                                                     └─────────┘
```

## Security

- All tool inputs are validated via [Zod](https://zod.dev) 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
- Arc browser only supports active tab queries (no `include_all_tabs`)

## Contributing

```bash
git clone https://github.com/dla-kirito/macos-screen-mcp.git
cd macos-screen-mcp
npm install
npm run build    # TypeScript → dist/
npm run lint     # Type-check without emitting
```

## License

[MIT](LICENSE)