WebChatMCP.js

Website: https://webchatmcp.js-package.xyz · Source: https://github.com/JS-PACKAGE/WebChatMCP.js · License: Apache-2.0

English · 繁體中文 · 日本語

An MCP server with a built-in browser. It sends your prompt through the private / temporary chat of ChatGPT, Claude, Grok or Gemini and returns the answer — nothing is written to the account's chat history. Logging in is optional for ChatGPT and Gemini (they also work as a guest); Claude and Grok need a login.

---

English

What is it?

WebChatMCP.js is a local MCP (Model Context Protocol) server. It embeds a persistent Chromium browser (Playwright) so an MCP client can drive the web interface of ChatGPT, Claude, Grok and Gemini: prompts flow through private chats and answers come back as tool results. Every tool except webchat_close and webchat_release takes a provider (chatgpt default, claude, grok, gemini).

Features

• Built-in browser with persistent profile — logins survive restarts; one profile holds all four services.

• Works without logging in on ChatGPT and Gemini (guest). Claude and Grok require a login (a Grok guest is asked to sign up after sending and gets logged_out).

• Every webchat_ask opens a brand-new chat and attempts the service's private mode: | Service | How the private chat is entered | |---|---| | ChatGPT | https://chatgpt.com/?temporary-chat=true | | Claude | https://claude.ai/new?incognito= | | Grok | https://grok.com/c#private | | Gemini | https://gemini.google.com/app, then the Temporary chat button is clicked (the URL cannot enter it directly; guests have no such button) |

  Guest use or unconfirmed private mode is noted in the result; Gemini guests have no temporary-chat button. Data retention and training policies are determined by the chosen service, not guaranteed by this server.

• The answer text is captured from the service's own response bubble and returned to the MCP client.

• webchat_models lists the models and the thinking depth (ChatGPT slider, Claude effort, Gemini extended thinking) of your account, live from the menus; webchat_ask can switch the model (model) and then the thinking depth (thinking) per prompt, using the labels from webchat_models.

• webchat_logout signs out without showing any window; webchat_login checks first and only shows a window when a manual login is really needed.

• Honest state probing: login and private-chat detection return true / false / unknown, never guesses.

• Clear error codes (logged_out, composer_not_found, no_response, …) instead of silent failures.

Requirements

• Node.js ≥ 22
• Optional: an account on the service you want to use (required for Claude and Grok)
• The browser is headless by default; a window only appears when a manual login (or a Cloudflare / age check) needs you

Install

git clone https://github.com/JS-PACKAGE/WebChatMCP.js.git
cd WebChatMCP.js
npm install
npx playwright install chromium   # one-time: the built-in browser
npm run build

Automatic install, background service and update (scripts)

The scripts in script/ set up Node.js (if it is missing or older than 22, an official build is downloaded to ~/.webchatmcp/node and its SHA-256 is verified), the dependencies and the built-in browser, build the project, then register and start it as a background service. No administrator rights needed.

| OS | Script | Background mechanism | |---|---|---| | macOS | script/install.sh | launchd LaunchAgent (starts at login, restarts on crash) | | Linux | script/install.sh | systemd --user (falls back to nohup) | | Windows | script/install.ps1 | Task Scheduler (starts at logon, hidden window, restarts on failure) |

Remote one-line install (installs git and Node.js if missing, git clones the source into ~/.webchatmcp/app (Windows: %USERPROFILE%\.webchatmcp\app), then installs and starts the service):

# macOS / Linux
curl -fsSL https://webchatmcp.js-package.xyz/script/install.sh | bash
curl -fsSL https://webchatmcp.js-package.xyz/script/install.sh | bash -s -- update     # update

# Windows (PowerShell)
& ([scriptblock]::Create((irm https://webchatmcp.js-package.xyz/script/install.ps1).TrimStart([char]0xFEFF)))            # install
& ([scriptblock]::Create((irm https://webchatmcp.js-package.xyz/script/install.ps1).TrimStart([char]0xFEFF))) update     # update

Missing git is installed with Homebrew on macOS (or by triggering the Command Line Tools installer), with the package manager on Linux (needs sudo unless root), and as MinGit under %USERPROFILE%\.webchatmcp\git on Windows (SHA-256 verified). Or clone the repository yourself and run the scripts from inside it:

# macOS / Linux
git clone https://github.com/JS-PACKAGE/WebChatMCP.js.git && cd WebChatMCP.js
script/install.sh                # install and start (default action: install)
script/install.sh update         # update: stops the running service → git pull → rebuild → restart
script/install.sh status         # status  (also: start / stop / restart / logs / uninstall)

# Windows (PowerShell)
git clone https://github.com/JS-PACKAGE/WebChatMCP.js.git; cd WebChatMCP.js
powershell -ExecutionPolicy Bypass -File script\install.ps1            # install and start
powershell -ExecutionPolicy Bypass -File script\install.ps1 update     # update (same as above)
powershell -ExecutionPolicy Bypass -File script\install.ps1 status     # also: start / stop / restart / logs / uninstall

• Update first runs git fetch and does nothing when you are already up to date (--force / -Force rebuilds anyway). Otherwise it stops the running service and any leftover WebChatMCP.js processes (including instances an MCP client started over stdio), updates, then starts the service again. It aborts if the working tree has uncommitted changes.
• The service is reached over HTTP: http://127.0.0.1:8321/mcp. Put environment variables in ~/.webchatmcp/webchatmcp.env (Windows: %USERPROFILE%\.webchatmcp\webchatmcp.env) as KEY=VALUE lines, then restart.
• The service and a stdio instance share one browser profile — pick one connection style.
• Self-start: after install the service starts automatically at login (on Linux also at boot without a login when linger is enabled) and restarts if it crashes; status shows the auto-start state. macOS uses a LaunchAgent, Linux systemd --user (crontab @reboot in the nohup fallback), Windows Task Scheduler (at logon).
• Uninstall: script/uninstall.sh (Windows: script\uninstall.ps1) stops the running service, then removes the service registration and its autostart setup (launchd plist / systemd unit / crontab @reboot / scheduled task, plus linger if the script enabled it). The source, the logged-in profile and the env file are kept by default (--purge / -Purge also removes Node.js, git, logs, the env file and the source downloaded by a remote install; --purge-profile / -PurgeProfile also deletes the profile).
• If the browser cannot start on Linux, run npx playwright install-deps chromium as root. The Windows script has not been verified on a real Windows machine.

MCP client configuration

{
  "mcpServers": {
    "webchatmcp": {
      "command": "node",
      "args": ["/absolute/path/to/WebChatMCP.js/dist/WebChatMCP.js"]
    }
  }
}

Or connect directly over HTTP (Streamable HTTP) — no child process needed:

http://127.0.0.1:8321/mcp

Both transports run at the same time. The port is written in src/config.ts (SERVER.httpPort, default 8321) and can be overridden with WEBCHATMCP_PORT; WEBCHATMCP_HOST=0.0.0.0 exposes it to the LAN (0 disables HTTP).

First run

1. Guest use needs no setup: call webchat_ask with your prompt (provider defaults to chatgpt).
2. To use your account (or Claude / Grok): call webchat_login with the provider. If you are already logged in, it returns immediately and shows no window; otherwise a window opens, you log in manually, and it is hidden again.
3. To sign out: call webchat_logout (no window).

If login opens a new tab, the server follows it. Fast replies are captured even when they appear immediately on send. Grok asks you to confirm your age once; the server never fills that in for you — run webchat_login with provider=grok and answer it in the window. After updating or rebuilding, restart the MCP server to load the new code (the saved profile is retained).

Tools

Every tool except webchat_close and webchat_release accepts provider? (chatgpt | claude | grok | gemini, default chatgpt; webchat_status defaults to the service of the current page).

| Tool | Input | Output | |---|---|---| | webchat_login | provider?, timeout_seconds? | login status JSON (alreadyLoggedIn) | | webchat_logout | provider? | JSON: cleared domains and the login state afterwards | | webchat_ask | provider?, prompt, model?, thinking?, timeout_seconds? | the answer text (a note is appended for guest use or unconfirmed private mode) | | webchat_models | provider? | JSON: models and thinking lists (label, current) | | webchat_status | provider? | browser / login / private-chat state JSON, plus cdp.enabled / cdp.endpoint | | webchat_close | — | close the built-in browser (logins stay saved) | | webchat_warmup | provider?, model? | preload the service's private chat page, and select model ahead of time (for host integrations) | | webchat_release | — | close the background browser when no webchat model is in use |

As soon as a question's prompt is sent, the server loads the next private chat page — with the same model/thinking — in a separate background tab while the answer is still generating, so the next question (typically the next round of an agent tool loop) skips the page load and model selection. webchat_warmup preloads a service's page ahead of the first question. The Oh My Pi and Pi plugins call it for you: switching to a webchat model preloads that service's page, and switching away to another model (or quitting) calls webchat_release to close the browser. Hosts that send no such signal (the Codex, Claude, Grok and Hermes bridges, plain MCP clients) rely on the idle timeout instead: the headless browser is closed 600 seconds after the last call and restarts on the next question (set WEBCHATMCP_IDLE_CLOSE_SECONDS; 0 disables it). A visible browser window (login in progress, WEBCHATMCP_HEADLESS=0) is never closed or preloaded automatically.

This parallel preload starts only when no other browser operation is queued (otherwise it is scheduled after the answer) and never delays the current answer; the answered tab is closed when that question finishes. A new browser operation cancels an unfinished preload and closes its separate tab, but a compatible next question or same-setting webchat_warmup takes over the page already loading; cancelling a question also cancels its unfinished preload. Repeated warmup preserves an unused, valid page instead of navigating again; each question still consumes a fresh private chat exactly once. Preloading also supports thinking without model, and reapplies thinking after a model change when needed. Navigation continues when the composer or login button appears; response completion retains the original stability checks.

Cancellation: when an MCP client sends notifications/cancelled, a bridge connection drops, or Oh My Pi / Pi aborts a reply, the server stops that question at the next safe point: nothing is typed or sent if the prompt was not sent yet; otherwise it makes a best-effort attempt to press the page's stop button,