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

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:

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:

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

Or add it to Claude Code:

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 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 for the complete boundary and reporting instructions.

Development

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

See 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