Terry Yao's Blog

Claude Code 接瀏覽器 MCP 與私有 plugin marketplace 的踩坑紀錄

Claude Code 接瀏覽器 MCP 與私有 plugin marketplace 的踩坑紀錄

閱讀時間約 9 分鐘

問題

我想給 Claude Code 設一個「一起看網頁」的瀏覽器通道，順便把散在各專案、一份份複製的 skill 收斂成一個私有 plugin marketplace。兩件事都不難，但設定雷一個接一個，卡了很久。

下面每條都標來源：官方文件或 release 紀錄有寫的附連結（2026-10-11 查閱），只有我實測的標「實測」。

Browser MCP

--headed 是不存在的參數

我照直覺在設定裡寫了 npx @playwright/mcp --headed，結果 server 一啟動就因為 unknown option 掛掉，claude mcp list 顯示 Failed to connect。（實測）

Playwright MCP 預設就是 headed（有可見視窗），要隱藏視窗才加 --headless。官方 README 的選項表只有 --headless，說明寫的是「run browser in headless mode, headed by default」（microsoft/playwright-mcp README）。所以設定寫 npx @playwright/mcp 就好。

教訓：設任何工具參數前，先 --help 看有沒有那個 flag，不要照直覺猜。

claude mcp list 的 Failed to connect 可能是假警報

claude mcp list 會對每個 server 做連線檢查，顯示 ✔ Connected 或 ✘ Failed to connect 之類的狀態（Claude Code MCP 文件）。

我遇到的情況是：用 npx 啟動的 server 比較慢，檢查等不到就判失敗，但 server 其實是好的。（實測；文件另外提到 server 啟動逾時可以用 MCP_TIMEOUT 環境變數調整，同上連結）

要確認 server 本身活著，我改成手動送一個 MCP 的 initialize 請求，看有沒有回 serverInfo：

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0.0.1"}}}' | npx @playwright/mcp

initialize 是 MCP 連線的第一步，server 必須回自己的 capabilities 和 serverInfo（MCP 規格：Lifecycle）。有回就代表 server 能起來，問題在檢查的時機。

Playwright CLI 和 MCP 帶的瀏覽器版本對不上

我另外用 npx playwright（CLI）想直接截圖，結果報 Executable doesn't exist。原因是 CLI 的版本和已經裝好的 chromium build 對不上。

Playwright 官方文件寫得很直接：每個 Playwright 版本都需要特定版本的瀏覽器執行檔，所以每次更新 Playwright 都可能要重跑 install（Playwright 文件：Browsers）。

具體數字：

  • Playwright 1.62.1 綁的是 chromium revision 1234（playwright v1.62.1 的 browsers.json）。
  • @playwright/mcp 自己依賴的是 Playwright 的 alpha 版，例如 0.0.83 依賴 1.64.0-alpha-…（npm registry：@playwright/mcp）。所以 MCP 帶的那份 chromium，跟你另外裝的 Playwright CLI 很可能不是同一個 build。
  • 我當時看到 MCP 那份是 1194～1208 一帶的 build（未查證：沒有逐版核對當時的 MCP 版本）。

解法二選一：用 CLI 那個版本補裝對應的瀏覽器，或直接用 MCP 自帶的那份，不要混用。

兩種瀏覽器 MCP 對應兩種需求

需求做法
開一個獨立的可見視窗看公開頁面@playwright/mcp：預設用它自己的 persistent profile，跟你平常用的瀏覽器分開
接你現有的瀏覽器分頁（帶你已經登入的狀態）裝瀏覽器擴充接進去，例如 @browsermcp/mcp（browsermcp.io）；Playwright MCP 也有 --extension（Chrome／Edge）和 --cdp-endpoint 可以接到已在執行的瀏覽器

@browsermcp/mcp 我實測要先在那個分頁點擴充的「Connect」才會動。Playwright MCP 的 profile 行為、--extension、--cdp-endpoint 見 README。

接自己已登入的瀏覽器時，等於把登入態交給 agent 操作，範圍要自己想清楚。

MCP 在 session 啟動時才連

改了 MCP 設定，要開新 session 才會生效。在 VS Code extension 裡，我是用 Cmd+Shift+P → Developer: Reload Window 再開新對話；/clear 不會重新載入 MCP。（實測）

Plugin marketplace：設定分兩層，是所有困惑的根源

把複製來複製去的 skill 收斂成私有 plugin 時，我卡最久的是這件事：「有沒有安裝」和「有沒有啟用」記在兩個不同的地方。

  • 安裝登記：~/.claude/plugins/installed_plugins.json，記每一筆安裝的 scope、路徑、版本。
  • 啟用旗標：settings 檔裡的 enabledPlugins，是開關。

（Plugin loading reference）

由這個結構推出來的幾件事：

  • 光寫 enabledPlugins 不等於安裝。 我實測只在專案的 .claude/settings.json 寫 enabledPlugins，plugin 沒有載入。正解是跑 claude plugin install <name>@<marketplace> --scope <user|project|local>。文件現在的說法更精確：只有專案 settings 設 true 時，Claude Code 不會自動抓沒裝過的 plugin，/plugin 的 Errors 分頁會顯示「enabled in project settings but isn’t installed here」；例外是 marketplace entry 用相對路徑來源的 plugin，它不需要安裝登記（同上連結）。所以結果跟 plugin 的來源類型有關。
  • 從 settings 拿掉 enabledPlugins 不等於解除安裝。 登記還在，/plugin 那一列不會消失。要真的移掉，在該專案目錄跑 claude plugin uninstall <name>@<marketplace> --scope project。我實測這個指令是靠目前所在目錄判斷是哪個專案，不吃路徑參數。
  • 散佈腳本也要真的跑 install，不能只複製一份含 enabledPlugins 的 settings。

per-project 安裝會把 /plugin 畫面塞爆

claude plugin list 和 /plugin 會把所有專案的 project-scope 安裝攤平列出。同一個通用 plugin 用 --scope project 裝進很多專案，畫面就是一長串一模一樣的列。功能正常，純粹難看、難找。（實測）

我最後定下的收斂方式：

  • 通用的 plugin 裝在 user scope，全域一份，各專案不用再宣告，新專案自動就有。
  • 領域型的 plugin（前端、資安、infra 之類）才 per-project 安裝，只裝在需要的專案。
  • 不要雙重宣告：同一個 plugin 在 user 和 project 都裝，會顯示兩列。升到全域時，要把各專案那筆 project 登記清掉。（實測）
  • 全域開著、某個專案要關：在該專案的 .claude/settings.local.json 寫 "<name>@<marketplace>": false。enabledPlugins 依來源優先序逐鍵合併，local 高於 project 和 user（Plugin loading reference：Find where a plugin is enabled）。

其他

  • 本機目錄可以直接當 marketplace：claude plugin marketplace add <本機路徑>，免推遠端。相對路徑的 plugin 會從那個資料夾原地載入，改了檔案在下次開 session 或 /reload-plugins 時生效（Create a marketplace、Plugin loading reference）。推論：如果那個資料夾是 git repo，它讀的就是當下 checkout 的分支，所以 marketplace 的內容留在 main 才穩。
  • 退役舊的 skill 複本用「搬走」，不要「刪」，也不要原地改名：把要退役的 skill 從 .claude/skills/<name> 搬到 .claude/skills/ 以外的資料夾，等於停用，還能當備份、隨時搬回來。只在 skills/ 底下改資料夾名稱沒用——skills/任何資料夾/SKILL.md 還是會被載入，反而跟 plugin 裡那份重複。（實測）

怎麼預防再次發生

  • 加 MCP server 後，別只信 claude mcp list；用 initialize 握手確認 server 本身活著。
  • 設工具參數前先 --help。--headed 就是猜錯的。
  • MCP 改設定要開新 session；VS Code 用 Reload Window，不是 /clear。
  • Playwright CLI 和 Playwright MCP 各用各的瀏覽器，不要混。
  • plugin 要生效就跑 claude plugin install，別只寫 enabledPlugins；要移除就跑 uninstall，別只刪 enabledPlugins。
  • Playwright MCP 選項
  • MCP initialize 握手
  • Claude Code plugin scope 與 enabledPlugins 優先序

關係圖譜