Skip to main content
Glama
README.md
# Grok Bot ↔ Claude bridge

An MCP server that lets Claude drive the **Grok Bot desktop app** (v0.79.4) on this PC.

Grok Bot has no public API, so the bridge starts the app with Chromium's DevTools port
(`127.0.0.1:9333`, local only) and operates its chat window directly: it types into the
prompt box, presses Enter, and reads replies back from the transcript. Replies are "done"
when the app's own announcement changes from "*bot* is working" to "*bot* replied".

> Unofficial. Not made or supported by Grok Bot. Windows only for now; Node 22+.

## Install

```bash
git clone https://github.com/harkawataryan/grok-bridge.git
cd grok-bridge
npm install
```

Install and sign in to Grok Bot first. The bridge looks for it at
`%LOCALAPPDATA%\Programs\Grok Bot\Grok Bot.exe`. Set `GROK_BOT_EXE` if it's somewhere else,
and `GROK_CDP_PORT` to use a debug port other than 9333.

## Tools

| Tool | What it does |
|---|---|
| `grok_send` | Send a message (optionally to a named bot) and wait for the reply (default 120 s) |
| `grok_read` | Read the last N messages; can wait until the bot is idle |
| `grok_list_bots` | List bots, which one is open, and whether it's working |
| `grok_select_bot` | Switch to another bot |

| `grok_window` | Show the Grok Bot window (to watch or take over) or hide it again |

If Grok Bot isn't running, or was started normally without the debug port, the bridge
(re)starts it with the port. You stay signed in.

**Runs hidden.** When the bridge starts Grok Bot, the window starts hidden: no pop-up and no
taskbar button. It's also launched with Chromium's background throttling off, so hidden replies
arrive at full speed. To see it, ask Claude to show it (`grok_window`) or just open Grok Bot
from the Start menu. Set `GROK_HIDDEN=0` to launch it visibly instead. If you already have
Grok Bot open (with the debug port), the bridge leaves your window alone.

## Claude Desktop / Claude Code (local, stdio)

```json
"mcpServers": {
  "grok-bot": { "command": "node", "args": ["<this folder>/server.mjs"] }
}
```

Claude Code (also what the Claude Desktop **Code** tab uses):
`claude mcp add --scope user grok-bot -- node "<this folder>/server.mjs"`

The Chat tab reads `claude_desktop_config.json`; the Code tab reads Claude Code's own config
(`~/.claude.json`), so register it in both if you use both. Either way, fully quit and reopen
Claude Desktop (or start a new session) afterwards, because running sessions don't pick up new servers.

## Claude on web / phone

Two options:

1. **Through your desktop (recommended, nothing exposed):** keep Claude Desktop running on
   this PC with the bridge installed, and talk to it from your phone via Remote Control /
   Dispatch. The phone sends instructions to the desktop session, and the desktop session calls the bridge.
2. **As a custom connector (works in claude.ai chats and the mobile app):** run the bridge in
   HTTP mode behind a tunnel, then add `https://<your-host>/mcp/<token>` in claude.ai →
   Settings → Connectors → Add custom connector. The token is in `.bridge-token` and is the
   only thing protecting access. Anyone with the URL can make your bot place calls and
   send email, so keep it private. To rotate it, delete `.bridge-token` and restart the bridge.

   **Cloudflare Tunnel on your own domain (free):**
   ```bash
   cloudflared tunnel login                      # approve your domain in the browser
   cloudflared tunnel create grok-bridge
   cloudflared tunnel route dns grok-bridge grok.example.com
   ```
   `~/.cloudflared/config.yml`:
   ```yaml
   tunnel: <tunnel-id>
   credentials-file: C:\Users\<you>\.cloudflared\<tunnel-id>.json
   ingress:
     - hostname: grok.example.com
       service: http://127.0.0.1:8790
     - service: http_status:404
   ```
   `remote.ps1` keeps the bridge (HTTP mode) and the tunnel running and restarts either one if it
   stops; `remote-start.vbs` starts it with no window. Run it at login with a scheduled task
   (not a shell you might close, or an app like Claude Desktop, which takes its child processes
   down with it when it restarts):
   ```powershell
   $a = New-ScheduledTaskAction -Execute wscript.exe -Argument '"<this folder>\remote-start.vbs"'
   $s = New-ScheduledTaskSettingsSet -ExecutionTimeLimit 0 -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -MultipleInstances IgnoreNew
   Register-ScheduledTask 'Grok Bridge (remote)' -Action $a -Trigger (New-ScheduledTaskTrigger -AtLogOn -User $env:USERNAME) -Settings $s
   Start-ScheduledTask 'Grok Bridge (remote)'
   ```
   Logs go to `logs/`.
   The PC has to be on and awake for the connector to work. (ngrok works too, e.g.
   `ngrok http 8790 --url <your-static-domain>`.)

## Notes / limits

- It drives the UI, so a Grok Bot update that renames its CSS classes
  (`sand-prompt-field`, `sand-transcript-row`, …) can break it. The selectors are in `grok.mjs`.
- While the debug port is open, any program on this PC can control the Grok Bot window.
  It is never reachable from the network.
- There's no "stop the bot" tool: the app has no stop control I could verify.
- `node test-client.mjs` runs a quick self-test, which sends one test message to the open bot.

TDQS

A3.7/5.0

Scored across 4 tools

Disambiguation5/5

Each tool targets a distinct action on a distinct concern: sending a message, reading messages, listing bots, and switching the active bot. There is no realistic way to confuse send with read, or list_bots with select_bot, since the descriptions explicitly contrast them (e.g. grok_send tells the agent to use grok_read afterward).

Naming Consistency5/5

All four tools use a single predictable scheme: the `grok_` prefix followed by a lowercase snake_case verb, with `_bots` appended when operating on the bot list. There is no mixing of camelCase, bare verbs, or alternative prefixes.

Tool Count4/5

Four tools is a lean but coherent surface for a desktop-app bridge, and each one earns its place (send/read for chat, list/select for bot management). It is on the thin side, and a couple more operations (e.g. starting a new chat) would round it out.

Completeness3/5

The core loop of listing/selecting a bot and sending/reading messages is covered, but there is no way to start a new chat/conversation, cancel or interrupt a running bot, or discover existing chats beyond the 'latest messages' read. These are notable gaps an agent could hit when the current chat is not the one it wants.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues