# grok-browser-mcp

MCP server that attaches to **your already-running Brave** over [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) (CDP). Grok CLI can then snapshot, click, type, and screenshot whatever tab you have open — same window, same logins.

It does **not** launch a fresh empty browser.

## Requirements

- Linux (Brave flags file `~/.config/brave-flags.conf`)
- [Brave](https://brave.com/)
- Node.js 18+
- [Grok CLI](https://github.com/xai-org)

## Install

```bash
git clone https://github.com/v76ADrR/grok-browser-mcp.git
cd grok-browser-mcp
npm install
```

## Enable CDP on Brave (once)

The Arch/CachyOS Brave wrapper reads `~/.config/brave-flags.conf`. Put:

```
--remote-debugging-port=9222
--remote-debugging-address=127.0.0.1
--remote-allow-origins=*
```

Restart Brave. Tabs usually restore. Confirm:

```bash
curl -s http://127.0.0.1:9222/json/version
```

Or call the MCP tool `browser_prepare` (this **restarts** Brave).

CDP is **localhost only**. Any process on this machine can control the browser while those flags are set. Remove them and restart Brave when you are done.

## Grok CLI config

`~/.grok/config.toml`:

```toml
[mcp_servers.browser]
command = "/usr/bin/node"
args = ["/ABS/PATH/TO/grok-browser-mcp/src/server.mjs"]
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 180
```

Reload: `/mcps` then `r`, or a new Grok session.

## Tools

| Tool | Purpose |
| --- | --- |
| `browser_status` | Brave PIDs + CDP health |
| `browser_prepare` | Write flags; restart Brave if CDP is down |
| `browser_tabs` | List / focus tabs |
| `browser_snapshot` | Clickable elements + refs |
| `browser_find` | Filter snapshot by text |
| `browser_click` | Click by ref / selector / text |
| `browser_type` / `browser_press` | Keyboard |
| `browser_evaluate` | JS in the page |
| `browser_screenshot` | JPEG of the current tab |
| `browser_navigate` / `browser_scroll` / `browser_wait` | Navigation |

Never call Playwright `browser.close()` on this connection — it would quit the user's Brave.

## License

MIT