# Browser Screenshot MCP

Give a local MCP client screenshots of one explicitly shared browser tab without granting access to every tab.

The Chromium extension has no global tab-list, debugger, cookie, history, web-request, content-script, or all-sites permission. A tab becomes available only after you open the extension on that tab and select **Share this tab**. Screenshots of that exact tab are then automatic until you stop sharing it or the capture session ends.

## Privacy model

1. A loopback-only daemon pairs with the extension using a random local token.
2. The extension creates an opaque capability and a video-only `tabCapture` stream when you explicitly share the active HTTP(S) tab.
3. Codex or Claude Code can list only the aliases and capabilities you shared—not the browser's tab list.
4. The shared tab displays an `AUTO` badge and remains available across navigation and while it is in the background.
5. The MCP client requests a screenshot for one capability. The extension reads the current frame without activating or focusing the tab.
6. The MCP client retrieves the image once; the bridge then deletes its in-memory copy.

There is no wall-clock share expiry. A share ends when you stop it, close the tab, restart the browser, reload the extension, or the capture stream otherwise ends. Incognito and non-HTTP(S) pages cannot begin a share. Chromium displays its own capture indicator for the lifetime of the stream.

## Requirements

- Node.js 22.18.0 or newer
- Chrome 116+, Brave, Edge, or another compatible Chromium browser
- Codex or Claude Code with local stdio MCP support

## Quick start

```sh
git clone https://github.com/szichedelic/browser-screenshot-mcp.git
cd browser-screenshot-mcp
npm ci
npm run build
REPO_DIR="$(pwd -P)"
```

Load the extension:

1. Open `chrome://extensions` or `brave://extensions`.
2. Enable **Developer mode**.
3. Select **Load unpacked** and choose the repository's `extension` directory.

Pair it with the local bridge:

```sh
node "$REPO_DIR/dist/cli.js" pairing-code
node "$REPO_DIR/dist/cli.js" serve
```

The first command copies the code to your system clipboard and never prints it. Leave the bridge running, open the extension's **Options**, paste the code, keep port `39393`, and save.

Add the MCP server to Codex:

```sh
codex mcp add browser-screenshot -- node "$REPO_DIR/dist/cli.js" mcp
codex mcp list
```

Or add it to Claude Code:

```sh
claude mcp add --transport stdio --scope user browser-screenshot -- node "$REPO_DIR/dist/cli.js" mcp
claude mcp get browser-screenshot
```

The MCP adapter starts the bridge automatically, so the manual `serve` process can be stopped after setup. See [Configuration](docs/CONFIGURATION.md) for client scopes, Windows commands, token rotation, custom paths, and troubleshooting.

## Use it

1. Open the page you want the agent to see.
2. Open the extension and select **Share this tab**. Use a non-sensitive alias such as `local-app`.
3. Navigate or switch tabs normally. The share remains bound to that same tab without requiring focus.
4. Ask your MCP client to list shared tabs and take a screenshot. No per-screenshot browser approval is required.
5. Select **Stop sharing** when finished.

Available MCP tools:

- `bridge_status`
- `list_shared_tabs`
- `request_screenshot`
- `get_screenshot`
- `stop_sharing`

There is intentionally no tool for enumerating browser tabs, matching titles or URLs, activating another tab, or capturing whichever tab happens to be active.

## Security boundaries

- The bridge binds only to `127.0.0.1` and authenticates the extension and MCP adapter.
- Only a user-provided alias—not the tab URL or title—is sent to the daemon.
- Tab and window IDs remain inside the extension.
- No audio track is requested, processed, or sent.
- Screenshots are not written to disk by this project. Requests expire after two minutes and ready images are one-time reads.
- The pairing token is stored in browser-local extension storage and a user-only local configuration file.
- A dedicated browser profile containing only agent-safe tabs is recommended as an additional boundary.

This project does not defend against software already running as your operating-system user. Once an MCP client receives a screenshot, that client's own retention and data-handling policies apply. See [Security model](SECURITY.md) for the complete boundary and reporting instructions.

## Development

```sh
npm run check
npm test
npm run build
node dist/cli.js doctor
```

See [CONTRIBUTING.md](CONTRIBUTING.md) before changing permissions or the bridge protocol. The protocol deliberately never carries URLs, titles, cookies, page DOM, browsing history, stream identifiers, or an unshared-tab inventory.

## License

[MIT](LICENSE)