WebChatMCP.js

為什麼需要它

運作流程

安裝與更新

需求

• Node.js ≥ 22
• 選用：想用的服務的帳號（Claude 與 Grok 必須有）
• 預設無頭；只有人工登入（或 Cloudflare／年齡確認需要你處理）時才會顯示視窗

安裝

git clone https://github.com/JS-PACKAGE/WebChatMCP.js.git
cd WebChatMCP.js
npm install
npx playwright install chromium   # 首次：安裝內建瀏覽器
npm run build

自動安裝、背景執行與更新（腳本）

script/ 內的腳本會補齊 Node.js（沒有或低於 22 時，下載官方版本到 ~/.webchatmcp/node 並驗證 SHA-256）、相依套件與內建瀏覽器， 建置後註冊成背景服務並啟動，不需要系統管理員權限。

遠端一行安裝（沒有 git、Node.js 會自動補齊，並 git clone 原始碼到 ~/.webchatmcp/app（Windows 為 %USERPROFILE%\.webchatmcp\app），再安裝並啟動）：

# 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     # 更新

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

缺 git 時：macOS 用 Homebrew（沒有就觸發命令列工具安裝）、Linux 用套件管理員（非 root 需要 sudo）、Windows 下載 MinGit 到 %USERPROFILE%\.webchatmcp\git 並驗證 SHA-256。以下是自己先 clone 倉庫再執行的方式：

# macOS / Linux
git clone https://github.com/JS-PACKAGE/WebChatMCP.js.git && cd WebChatMCP.js
script/install.sh                # 安裝並啟動（預設動作 install）
script/install.sh update         # 更新：自動關掉執行中的服務 → git pull → 重新建置 → 重新啟動
script/install.sh status         # 狀態  （另有 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            # 安裝並啟動
powershell -ExecutionPolicy Bypass -File script\install.ps1 update     # 更新（同上）
powershell -ExecutionPolicy Bypass -File script\install.ps1 status     # 另有 start / stop / restart / logs / uninstall

• 更新會先 git fetch 檢查有沒有新版，沒有就什麼都不做（加 --force／-Force 可強制重新建置）。有新版時，先關掉執行中的服務與殘留的 WebChatMCP.js 行程（包含 MCP 用戶端以 stdio 啟動的實例），再更新，完成後把服務啟動回來。工作區有未提交的修改時會中止更新。
• 服務以 HTTP 提供連線：http://127.0.0.1:8321/mcp。環境變數寫在 ~/.webchatmcp/webchatmcp.env（Windows 為 %USERPROFILE%\.webchatmcp\webchatmcp.env），格式 KEY=VALUE，改完 restart 生效。
• 背景服務與 stdio 實例共用同一個瀏覽器 profile，建議只選其中一種連線方式。
• 自起動：安裝後服務會在登入時自動啟動（Linux 啟用 linger 時，開機不登入也會啟動），異常結束會自動重啟；status 會顯示「自動啟動」狀態。macOS 用 LaunchAgent、Linux 用 systemd --user（退回 nohup 時用 crontab 的 @reboot）、Windows 用工作排程器（登入時）。
• 反安裝：script/uninstall.sh（Windows 為 script\uninstall.ps1）會先停掉執行中的服務，再移除服務註冊與自起動設定（launchd plist／systemd unit／crontab @reboot／排程工作，以及由腳本啟用的 linger）。原始碼、登入 profile 與設定檔預設保留（加 --purge／-Purge 連 Node.js、git、日誌與設定檔（含遠端安裝下載的原始碼）一起刪，加 --purge-profile／-PurgeProfile 才會刪掉登入 profile）。
• Linux 瀏覽器起不來時，用 root 執行 npx playwright install-deps chromium。Windows 腳本尚未在 Windows 實機上驗證。

MCP 用戶端設定

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

或以 HTTP 直連（Streamable HTTP），不必啟動子程序：

http://127.0.0.1:8321/mcp

兩種連線同時啟用。port 寫在 src/config.ts（SERVER.httpPort，預設 8321），可用 WEBCHATMCP_PORT 覆蓋；WEBCHATMCP_HOST=0.0.0.0 開放區網（0 停用 HTTP）。

首次使用

1. 訪客使用（ChatGPT、Gemini）不需設定：直接呼叫 webchat_ask 送出提示（provider 預設 chatgpt）。
2. 想用自己的帳號（或使用 Claude／Grok）：以 provider 呼叫 webchat_login。已登入就立刻回傳、不顯示視窗；否則開啟視窗讓你人工登入，完成後收回。
3. 要登出：呼叫 webchat_logout（不顯示視窗）。

登入若開啟新分頁，伺服器會切換過去；立即出現的快速回覆也能擷取。Grok 首次使用會要你確認年齡，伺服器不會代填——請以 provider=grok 呼叫 webchat_login，在視窗中自行回答。更新或重新 build 後，請重啟 MCP 伺服器以載入新程式碼（原有 profile 保留）。

環境變數

外掛（plugins/）

用一個 JSON 檔就能新增其他聊天服務：放進 plugins/ 或使用者目錄 ~/.webchatmcp/plugins/，啟動時載入，並加入所有工具的 provider 選項（檔名以 _ 開頭的是範本，不會載入）。外掛只是網址與 DOM 選擇器的資料，不會執行任何程式碼。格式、欄位與寫法見 plugins/README.md 與範本 plugins/_template.json；格式錯誤的外掛會被略過，原因寫在 stderr。請只放你信任的外掛。

Oh My Pi 外掛：plugins/omp/ 內有 omp 的擴充，讓 omp 把 WebChatMCP 當成模型提供商 webchat。先 /webchat-refresh 才有模型，id 是 webchat/<服務>/<模型標籤>；/webchat-login 不帶參數會檢查 ChatGPT、Claude、Grok、Gemini。沒有模型標籤的服務名稱不會進清單。以腳本安裝與反安裝（不需要 root／系統管理員）：

# Linux / macOS
plugins/omp/install.sh
plugins/omp/uninstall.sh            # 反安裝；--purge 另刪模型快取

# Windows（PowerShell）
powershell -ExecutionPolicy Bypass -File plugins\omp\install.ps1
powershell -ExecutionPolicy Bypass -File plugins\omp\uninstall.ps1      # -Purge 另刪模型快取

每個外掛都附安裝與反安裝腳本。所有模型外掛（omp、pi、Codex、Claude、Grok、Hermes）都支援本機工具往返：宿主把你的問題與它的工具清單送來；網頁模型只會用嚴格的 JSON 信封「提出要求」（綁定每次請求的隨機 nonce，並比對宿主的工具名稱與必要參數，隨便寫出的文字永遠不會被執行）；外掛把它轉成宿主原生的工具呼叫；宿主依自己的權限與確認設定在本機執行，結果再送回網頁模型，直到它給出答案。每次網頁聊天都是全新的無痕聊天，所以每一輪都會重新帶入系統提示（截斷到 24k 字元）、對話、先前的工具要求與結果（每則結果截斷到 50k 字元）。你讓宿主讀取的檔案內容與指令輸出，會傳到所選服務的平台。沒有串流；安裝細節與限制見 plugins/omp/README.md。

Codex 外掛：plugins/codex/ 讓 Codex 的模型選單多出名稱結尾為 (WEB) 的網頁模型（如 ChatGPT · GPT-5.5 (WEB)；沒有模型標籤的服務名稱不會進清單）。選了它們就經由 WebChatMCP 走無痕聊天；官方模型的請求原樣轉送官方後端。腳本會先關閉所有執行中的 Codex，再改 ~/.codex/config.toml 的 openai_base_url（關不掉就提示你手動關閉，且不動設定），反安裝時還原：

# Linux / macOS
plugins/codex/install.sh
plugins/codex/uninstall.sh          # 反安裝；--purge 另刪備份

# Windows（PowerShell）
powershell -ExecutionPolicy Bypass -File plugins\codex\install.ps1
powershell -ExecutionPolicy Bypass -File plugins\codex\uninstall.ps1      # -Purge 另刪備份

本機工具往返（由 Codex 執行工具）、沒有串流；WebChatMCP 伺服器沒開時官方模型也會連不上等注意事項見 plugins/codex/README.md。

Claude 外掛：plugins/claude/ 讓 Claude Code 的 /model 選單多出名稱結尾為 (WEB) 的網頁模型（如 ChatGPT · GPT-5.5 (WEB)；沒有模型標籤的服務名稱不會進清單）。選了它們就經由 WebChatMCP 走無痕聊天；官方模型的請求原樣轉送 api.anthropic.com。腳本會先關閉所有執行中的 Claude（CLI 與桌面 App），再改 ~/.claude/settings.json 的 env.ANTHROPIC_BASE_URL 與 modelPicker（關不掉就提示你手動關閉，且不動設定），反安裝時還原：

# Linux / macOS
plugins/claude/install.sh
plugins/claude/uninstall.sh          # 反安裝；--purge 另刪備份

# Windows（PowerShell）
powershell -ExecutionPolicy Bypass -File plugins\claude\install.ps1
powershell -ExecutionPolicy Bypass -File plugins\claude\uninstall.ps1      # -Purge 另刪備份

本機工具往返（由 Claude Code 執行工具）、沒有串流；WebChatMCP 伺服器沒開時官方模型也會連不上等注意事項見 plugins/claude/README.md。

Grok 外掛：plugins/grok/ 以自訂模型的方式，讓 Grok Build（grok CLI）的模型選單多出名稱結尾為 (WEB) 的網頁模型（如 ChatGPT · GPT-5.5 (WEB)；沒有模型標籤的服務名稱不會進清單）。只有這些模型經由 WebChatMCP 走無痕聊天，官方模型完全不受影響。腳本會先關閉所有執行中的 grok（含常駐的 leader 行程），再在 ~/.grok/config.toml 加一段標記區塊（關不掉就提示你手動關閉，且不動設定），反安裝時移除：

# Linux / macOS
plugins/grok/install.sh
plugins/grok/uninstall.sh          # 反安裝；--purge 另刪備份

# Windows（PowerShell）
powershell -ExecutionPolicy Bypass -File plugins\grok\install.ps1
powershell -ExecutionPolicy Bypass -File plugins\grok\uninstall.ps1      # -Purge 另刪備份

本機工具往返（由 Grok Build 執行工具）、沒有串流；細節見 plugins/grok/README.md。

Pi 外掛：plugins/pi/ 內有 pi 的擴充，讓 pi 把 WebChatMCP 當成模型提供商 webchat。先 /webchat-refresh 才有模型，id 是 webchat/<服務>/<模型標籤>；/webchat-login 不帶參數會檢查 ChatGPT、Claude、Grok、Gemini。沒有模型標籤的服務名稱不會進清單。以腳本安裝與反安裝（不需要 root／系統管理員；裝完請重啟 pi）：

# Linux / macOS
plugins/pi/install.sh
plugins/pi/uninstall.sh            # 反安裝；--purge 另刪模型快取

# Windows（PowerShell）
powershell -ExecutionPolicy Bypass -File plugins\pi\install.ps1
powershell -ExecutionPolicy Bypass -File plugins\pi\uninstall.ps1      # -Purge 另刪模型快取

本機工具往返（由 pi 執行工具）、沒有串流；細節見 plugins/pi/README.md。

Hermes 外掛：plugins/hermes/ 讓 Hermes Agent 把 WebChatMCP 當成模型提供商 webchat（模型 id 是 <服務>/<模型標籤>，先 refresh；chatgpt 這種沒有模型的名稱不會進清單）。沒有 env_vars 就不會註冊；明確指定時沒有金鑰會直接失敗，不會改走別家。fallback_models 留空，只是 GET /models 失敗時的選單後備。安裝腳本寫入假的 WEBCHAT_API_KEY（橋接不驗證），不改 model.provider：

# Linux / macOS
plugins/hermes/install.sh
plugins/hermes/uninstall.sh            # 反安裝；--purge 另刪模型快取

# Windows（PowerShell）
powershell -ExecutionPolicy Bypass -File plugins\hermes\install.ps1
powershell -ExecutionPolicy Bypass -File plugins\hermes\uninstall.ps1      # -Purge 另刪模型快取

本機工具往返（由 Hermes 執行工具）、沒有串流；細節見 plugins/hermes/README.md。

工具一覽

安全與資料

1. 伺服器不讀、不存任何密碼、cookie 或 token——登入只透過使用者在瀏覽器中人工操作；webchat_logout 只清除該服務網域的 cookie。
2. thinking 在選完 model 之後才套用（可選的深度會隨模型而異）。標籤不在清單內會回 thinking_not_found；沒有思考設定的服務（Grok 把它併在模式裡，請用 model 選）也一樣。Gemini 的開關項（如延伸思考）指定 thinking 只會把開關打開，已經開著就不會動它。
3. Codex 外掛：重新擷取時會對 ChatGPT、Claude、Gemini 逐一切換模型，讀出各模型自己的思考深度（較慢，但只在重新擷取時）。網頁上有兩段以上深度（ChatGPT 滑桿、Claude 努力程度）的模型，會把它們宣告成 Codex 的 reasoning 選項，值就是網頁標籤原樣，選了之後會在送出前先在網頁設好；只有開關型（Gemini）或沒有設定（Grok）的模型維持單一 medium，且會被忽略。其他宿主外掛目前還不會傳思考深度。
4. HTTP endpoint 無認證，預設只綁 127.0.0.1；以 0.0.0.0 開放區網前，請確認網路可信。
5. 提示與回覆會經過所選服務（ChatGPT、Claude、Grok、Gemini），適用該服務的資料使用政策。
6. 本專案與 OpenAI、Anthropic、xAI、Google 皆無隸屬關係；各服務名稱為其所屬公司的商標。