# ChatGPT Remote Browser MCP

An MCP server that exposes OpenClaw's Chrome-extension browser controls while
preserving the extension's **Selected Tabs** access boundary.

The server is designed for a topology in which ChatGPT reaches a private MCP
process through an outbound Secure MCP Tunnel, OpenClaw runs on a gateway host,
and Chrome may run on a different machine with the OpenClaw extension.

## Security model

- Only tabs currently shared by the OpenClaw extension are published.
- Raw Chrome/OpenClaw target IDs are replaced with opaque, short-lived handles.
- The current tab ACL is checked again before every operation.
- Revoked, expired, unknown, and closed handles fail with `ACCESS_DENIED`.
- Read-only operations may retry a small set of transient target-resolution
  errors. Mutating operations are never automatically retried.
- There is no generic shell, gateway RPC, Relay, or raw CDP passthrough.
- Upload paths are restricted to OpenClaw-owned inbound/upload locations.
- Generated file responses are capped at 20 MiB and temporary output is removed.

`native_browser` includes powerful operations such as JavaScript evaluation,
navigation, uploads, downloads, and tab lifecycle changes. Use MCP client
confirmations and share only tabs that are safe to automate.

See [Security](docs/SECURITY.md) for the complete trust model.

## Architecture

```text
ChatGPT / MCP client
        |
        | outbound/private MCP transport
        v
chatgpt-remote-browser-mcp (stdio)
        |
        | fixed OpenClaw browser CLI calls
        v
OpenClaw Gateway -> Chrome extension -> Selected Tabs ACL
```

See [Architecture](docs/ARCHITECTURE.md) for details.

## Tools

Compatibility tools:

- Viewer: `list_shared_tabs`, `snapshot`, `screenshot`
- Operator: `click`, `type`, `press`, `scroll`, `navigate`

Native high-level tool:

- `native_browser` actions: `tabs`, `open`, `focus`, `close`, `label`,
  `snapshot`, `screenshot`, `navigate`, `console`, `requests`, `errors`,
  `text`, `emulate`, `pdf`, `download`, `waitfordownload`, `upload`, `dialog`,
  `highlight`, `responsebody`, and `act`
- `act` kinds: `batch`, `click`, `clickCoords`, `type`, `press`, `hover`,
  `scrollIntoView`, `drag`, `select`, `fill`, `resize`, `wait`, `evaluate`, and
  `close`

Internal extension transport operations such as attach/detach are deliberately
encapsulated. Local profile lifecycle and Gateway administration are outside
the MCP surface.

## Requirements

- Node.js 22 or newer
- A working OpenClaw installation and browser profile
- OpenClaw Chrome extension paired with the Gateway
- Optional: an OpenAI Secure MCP Tunnel for private ChatGPT connectivity

## Install and run

```sh
npm ci
npm run check
npm test
npm install -g .
openclaw-browser-mcp
```

The MCP transport is stdio. Configuration is provided through environment
variables:

- `OPENCLAW_BIN`: OpenClaw executable; default `/opt/homebrew/bin/openclaw`
- `OPENCLAW_BROWSER_PROFILE`: browser profile; default `chrome`
- `OPENCLAW_BROWSER_TIMEOUT_MS`: backend timeout; default `30000`

## Private tunnel deployment

Generic deployment templates are in [`deploy/`](deploy/). They intentionally
contain placeholders rather than machine paths, tunnel identifiers, or
credentials. Render them locally into protected runtime configuration; never
commit the rendered files.

See [Deployment](docs/DEPLOYMENT.md) for setup, health checks, operation, and
rollback.

## Tests

```sh
npm run check
npm test
npm run test:e2e
npm run test:remote
npm run test:acl
npm audit --omit=dev
```

- Unit/schema/security suite: 22 cases
- Local managed-browser E2E
- Self-contained remote Chrome-extension E2E using a disposable tab
- Interactive ACL-revocation E2E

The remote E2E creates, shares, exercises, closes, and post-validates its own
tab. It does not require a manually prepared test tab. See
[Testing](docs/TESTING.md).

## Status

Version `0.2.2` has been validated with:

- 22/22 unit, schema, dispatch, and security tests
- local browser E2E
- remote Chrome-extension E2E across all compatibility tools and 16 native
  scenarios
- immediate `ACCESS_DENIED` after ACL revocation and after tab closure
- a private ChatGPT-to-MCP tunnel invocation
- zero known production dependency vulnerabilities at validation time

## License

[MIT](LICENSE)