vibe-mcp

# Vibe MCP - Browser Automation for AI Agents

[![npm version](https://img.shields.io/npm/v/@vibebrowser/mcp.svg)](https://www.npmjs.com/package/@vibebrowser/mcp)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

MCP server for [Vibe AI Browser](https://vibebrowser.app) — drive your **real, logged-in Chrome** from any MCP client, including agents running on a **different machine** with no inbound port open.

> ⚠️ **Security — treat your relay URL/UUID like a password.** A relay URL or extension UUID (`wss://relay.api.vibebrowser.app/<uuid>`) grants **live control of your browser session** (read your tabs, take screenshots, read page content). Never share it, paste it into a chat with untrusted parties, or commit it to a repo. Every example UUID in this documentation is a non-routable placeholder (`YOUR-EXTENSION-UUID` or `00000000-0000-0000-0000-000000000000`) — substitute your own secret value locally and keep it out of version control.

## Install prompt for AI agents (OpenClaw / Hermes)

Paste the block below into your **OpenClaw** or **Hermes** agent. Replace the last line with your remote value — the connector URL (`https://relay.api.vibebrowser.app/mcp/<uuid>`) shown in the Vibe extension's **Settings → AI Agent Control → Remote (internet) → Relay access** (a bare UUID or a `wss://` relay URL also still work). That's the only edit you make.

```text
You are setting yourself up to control my real Chrome through Vibe Browser. Work through the steps in order, and after each step confirm it worked before moving on. Do not claim a step is done until you have proven it.

1. Install the "vibebrowser" skill for your runtime:
   - OpenClaw:  npx -y skills add VibeTechnologies/vibe-mcp -s vibebrowser -a openclaw -g -y --copy --dangerously-accept-openclaw-risks
                then run `openclaw skills list` and confirm a "vibebrowser" row shows "ready" as installer registration.
   - Hermes:    npx -y skills add VibeTechnologies/vibe-mcp -s vibebrowser -y
                optional installer registration check: `npx -y skills list` shows a "vibebrowser" row.

2. Remember my remote so I only give it to you once. Save it to a file `vibebrowser-cli.md` in your persistent agent workspace root (the directory that holds your `memory/` folder — not the shell's working dir, not $HOME unless they are the same) as a line `remote: <value>`; if your runtime can also write memory keys, additionally store it under `vibebrowser_remote`. On every later command — including the first message of a new conversation — load it back from that file and reuse it without asking me again.

3. Record a standing rule so you route correctly later: whenever I ask you to do anything in MY browser / MY Chrome / MY tabs / the page I'm on, use this vibebrowser skill (`npx -y @vibebrowser/cli@latest` with my saved remote) to drive my REAL browser — never your built-in, headless, or in-pod browser, never web-fetch instead, and never run `vibebrowser`. Save this rule wherever your standing instructions/memory live so it applies in future conversations.

4. Confirm you can control my Chrome, retrying on "Extension reconnecting" (wait 3s, up to 5x):
   npx -y @vibebrowser/cli@latest --remote "<my remote>" --json status --wait-for-extension --wait-timeout 20000
   npx -y @vibebrowser/cli@latest --remote "<my remote>" --json snapshot --format aria

Then report: (1) is extensionConnected true, (2) did the snapshot return my real page content?

My remote: <PASTE YOUR CONNECTOR URL, UUID, OR wss:// URL HERE>
```

## Why Vibe MCP?

The browser-automation MCP space moved fast. Most of what used to differentiate us is now table stakes — so here is an honest scorecard. Where a competitor matches us, the column says **Yes**.

| Capability | Vibe MCP | Playwright MCP | Chrome DevTools MCP | Claude for Chrome | BrowserMCP |
|---|---|---|---|---|---|
| Uses your real profile / logged-in sessions | Yes | Yes ([`--extension`][pw-ext]) | Yes (own `--user-data-dir`) | Yes | Yes |
| No per-connection approval dialog | Yes | Yes ([token][pw-token]) | Yes (dedicated profile only) | Yes | Yes |
| **Real logged-in profile *and* no dialog, together** | **Yes** | Yes | **No** — [pick one][cdp-1794] | Yes | Yes |
| Multiple agents against one browser | Yes | Yes ([`--shared-browser-context`][pw-shared]) | Yes ([`--experimentalPageIdRouting`][cdp-pageid]) | No | No |
| **Agent on another machine, no inbound port** | **Yes** — extension dials **out** to a relay | No | No — needs an inbound debug port + forwarding | No | No |
| Works with any MCP client (Codex, OpenCode, Cursor, Hermes, OpenClaw) | Yes | Yes | Yes | **No** — Anthropic surfaces only | Yes |

Two rows are ours alone:

- **Outbound, cross-machine control.** The Vibe extension opens an outbound WebSocket to a relay (`wss://relay.api.vibebrowser.app/<uuid>`). Nothing listens on the user's machine, nothing is port-forwarded, and the agent can live in a pod, a cron job, or a chat bot. No competitor documents an extension-initiated outbound connection to a remote MCP server.
- **Real profile without the dialog tax.** Chrome DevTools MCP needs approval for *each* WebSocket connection to Chrome ([#1794][cdp-1794], open; persistence was [closed won't-fix][cdp-825]). The maintainer's workaround — `--remote-debugging-port` with a dedicated `--user-data-dir` — avoids the dialog by giving up your logged-in profile. So: **skip the dialog, or use your real profile — not both.**

Also worth knowing:

- **Vendor lock-in.** Claude for Chrome is GA, clicks and types via the `debugger` permission, and supports scheduled tasks — it is the closest competitor. But it only drives Anthropic's own surfaces (side panel, Claude Desktop connector, Cowork, Claude Code). There is no public API or MCP surface, so Codex, OpenCode, Hermes and OpenClaw cannot use it. Vibe MCP is agent-agnostic.
- **Stability.** Chrome DevTools MCP is explicitly experimental and currently carries open memory-leak ([#2431][cdp-2431], [#2291][cdp-2291], [#2456][cdp-2456]) and concurrency ([#1763][cdp-1763], [#1921][cdp-1921]) issues.

[pw-ext]: https://github.com/microsoft/playwright-mcp/tree/main/extension
[pw-token]: https://github.com/microsoft/playwright-mcp#browser-extension
[pw-shared]: https://github.com/microsoft/playwright-mcp
[cdp-pageid]: https://github.com/ChromeDevTools/chrome-devtools-mcp
[cdp-1794]: https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1794
[cdp-825]: https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/825
[cdp-2431]: https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2431
[cdp-2291]: https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2291
[cdp-2456]: https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/2456
[cdp-1763]: https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1763
[cdp-1921]: https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/1921

### Multi-Agent Architecture

Run Claude Desktop, Cursor, VS Code Copilot, and OpenCode at once — they share control of one browser through the relay, which multiplexes requests and routes each response back to the agent that asked.

```
Claude Desktop       Cursor          VS Code         OpenCode
     |                  |                |               |
     v                  v                v               v
 [vibebrowser-mcp] [vibebrowser-mcp] [vibebrowser-mcp] [vibebrowser-mcp]
     |                  |                |               |
     +------------------+----------------+---------------+
                        |
                        v
                  [Relay Daemon]  <-- Auto-spawned, handles multiplexing
                        |
                        v
                 [Vibe Extension]
                        |
                        v
                   [Your Chrome]
```

## Features

- **Multi-Agent Ready** - Run Claude, Cursor, VS Code, and more simultaneously against one browser
- **Uses Your Browser** - No separate browser instance, uses your existing Chrome with all your logins
- **Remote-capable** - The extension dials out to a relay, so the agent can run on another machine with no inbound port
- **Local by default** - In local mode everything stays on `127.0.0.1`; only remote relay mode routes traffic through `relay.api.vibebrowser.app`
- **Direct Chrome DevTools mode** - Extension tools stay primary by default; use `--devtools` to drive your real running Chrome directly over the DevTools Protocol (no extension required)


## Quick Start

### 1. Install the Vibe Extension

Install the Vibe AI Browser extension in Chrome, Brave, or any Chromium browser:

**Option A: Chrome Web Store (Recommended)**
1. Visit the [Chrome Web Store](https://chromewebstore.google.com/detail/vibe-ai-browser-co-pilot/djodpgokbmobeclicaicnnidccoinado)
2. Click "Add to Chrome"
3. The Vibe icon will appear in your toolbar

**Option B: Developer Version**
1. Download the [latest release ZIP](https://github.com/VibeTechnologies/VibeWebAgent/releases/latest/download/vibe-ai-copilot-latest.zip)
2. Extract to a permanent folder
3. Go to `chrome://extensions`, enable Developer Mode
4. Click "Load unpacked" and select the extracted folder

For detailed instructions, see the [installation guide](https://docs.vibebrowser.app/getting-started/extension).

### 2. Configure Your AI Application

<details>
<summary><strong>Claude Desktop</strong></summary>

Edit your Claude Desktop config file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "vibe": {
      "command": "npx",
      "args": ["-y", "@vibebrowser/mcp"]
    }
  }
}
```

Restart Claude Desktop after saving.

</details>

<details>
<summary><strong>Cursor</strong></summary>

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Go to "Features" -> "MCP Servers"
3. Click "Add Server" and add:

```json
{
  "vibe": {
    "command": "npx",
    "args":