@modelcontextprotocol/server-puppeteer：官方 Puppeteer MCP Server

🌏 English version

⚠️ 這個 server 已被官方封存，不要用在新專案。 @modelcontextprotocol/server-puppeteer 已從 MCP 官方 servers monorepo 移出，搬到 servers-archived；npm 上最後一個版本停在 2025.5.12，之後沒有再發佈。套件還裝得起來，但不再收 bug fix，也不會跟上 MCP spec 的變動。

要遷移的話有兩個方向：想要 Puppeteer 底層 + 截圖／除錯能力，換 Chrome 團隊官方維護的 chrome-devtools-mcp（它本身就是建在 Puppeteer 上的）；想要一般網頁自動化，換 @playwright/mcp。

下面的內容留著，是因為「精簡工具集 + 截圖回饋 + evaluate 逃生門」這組設計取捨仍然值得理解——你在評估其他 browser MCP 時會一再遇到同一組權衡。

@modelcontextprotocol/server-puppeteer 是 Anthropic MCP 官方 servers monorepo 裡的 Puppeteer 封裝，提供 7 個工具讓 AI agent 控制 Chrome。工具集刻意保持精簡，截圖作為主要的頁面狀態回傳方式，配合 puppeteer_evaluate 執行任意 JS。

安裝與設定

同樣用 npx 直接執行：

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

啟動後自動管理一個 Chrome 程序，不需要手動啟動瀏覽器。但 README 明確註記 NPX 版會開出可見的瀏覽器視窗（要無頭得走 Docker 版），跟 @playwright/mcp 預設 headed 是同一類坑。Console log 是暴露成 console://logs 這個 resource，由 client 自己去讀，不是自動塞回給 agent。

7 個核心工具

puppeteer_navigate 前往指定 URL，會等待頁面 load 事件完成。

puppeteer_navigate("https://example.com")

puppeteer_screenshot 截圖當前頁面或指定元素。三個容易踩的預設值：name 是必填（少了會直接噴錯）；encoded 預設 false，回傳的是 binary image content 而不是 base64；預設視窗是 width=800, height=600，而且它會呼叫 page.setViewport() 把頁面尺寸改掉。參數以原始碼與 README為準：

puppeteer_screenshot(name="main", selector="#main-content")

puppeteer_click 點擊 CSS selector 對應的元素。只有這個工具沒有等待——原始碼直接呼叫 page.click()，所以要自己確認元素已在 DOM 裡。（fill / select / hover 三個反而都會先跑 page.waitForSelector()，別把 click 的行為當成整個 server 的行為。）

puppeteer_click(selector="button[type='submit']")

puppeteer_fill 填入文字到輸入框。注意它不會清空——底層是 page.type()，等於往現有內容後面接著打，要覆寫得自己先清掉：

puppeteer_fill(selector="#email", value="user@example.com")

puppeteer_select 對 <select> 元素選值：

puppeteer_select(selector="#country", value="TW")

puppeteer_hover 滑鼠移到元素上方（觸發 hover 狀態、下拉選單展開等）：

puppeteer_hover(selector=".dropdown-trigger")

puppeteer_evaluate 在頁面 context 執行 JavaScript，回傳執行結果：

// 範例：抓取頁面所有連結
puppeteer_evaluate(script=`
  Array.from(document.querySelectorAll('a'))
    .map(a => ({ text: a.textContent.trim(), href: a.href }))
`)

evaluate 的實際用途

puppeteer_evaluate 是 server-puppeteer 相對彈性的地方。7 個工具沒有涵蓋的操作，很多可以用 JS 補上：

• 抓取沒有 ARIA label 的複雜資料結構
• 觸發 custom event（element.dispatchEvent(new Event('change'))）
• 讀取 localStorage / sessionStorage
• 操作 Shadow DOM 裡的元素（shadowRoot.querySelector(...))
• 等待非標準的非同步條件（輪詢直到某個 property 變化）

這讓 agent 在工具不夠用時有逃生門，但也意味著 agent 需要能寫 JS 才能充分利用這個工具。

截圖導向的取捨

server-puppeteer 最主要的特性是用截圖（puppeteer_screenshot）來讓 agent 確認頁面狀態。這個設計有明顯的取捨：

優點：

• 視覺確認直覺——agent 能看到和使用者完全相同的畫面
• 對 ARIA 屬性設得不好的頁面，截圖仍能提供足夠資訊
• 截圖本身就是輸出（OG 圖預覽、UI 回歸測試截圖）

缺點：

• 每張截圖的成本比直覺低但仍可觀：以 Anthropic 的視覺 token 表為例，1920×1080 在 standard tier 是 1,560 個 visual token（會先縮到 1456×819），high-res tier 是 2,691。長 session 一路累積下來還是很快
• 需要 vision 能力的模型（不能用純文字模型）
• 截圖包含大量 agent 不需要的視覺資訊（背景、樣式）

對比 @playwright/mcp 的 accessibility tree 模式，tree 確實省 token 且不需要 vision 模型；但兩者的實際倍數取決於頁面複雜度，不要套用固定倍率——同一頁的 tree 若是 2–10KB，換算下來與截圖是同一個量級，差距遠沒有坊間說的那麼誇張。

與 @playwright/mcp 的比較

工具數量少不代表功能弱——puppeteer_evaluate 本質上是萬用逃生口。但對需要可靠互動（等待、多 tab、複雜 locator）的 agent，Playwright MCP 的工具集更完整；何況現在多了一項決定性差異：一邊還在更新，一邊沒有了。

適合的場景

封存之後，「該不該選它」這題其實已經有答案了：不該。但它原本擅長的那些場景仍然存在，只是換人接手：

原本就不適合它的場景也沒變：長 session 的 agent 工作流（截圖 token 一路累積）、跨瀏覽器、需要複雜等待邏輯的操作（沒有 auto-wait）。

整體來說

server-puppeteer 是功能直接、上手快的選擇，evaluate 提供了一定的靈活性。但在 AI agent 場景，截圖導向的設計讓 token 成本成為長期限制——而它現在連「還有人維護」這個前提都沒有了。

值得留下的是它示範的那條光譜：工具集愈小、agent 要靠 evaluate 自己寫 JS 的比例愈高；頁面狀態愈依賴截圖、token 成本愈難壓。你評估任何一個 browser MCP，都可以拿這兩軸去量。至於實際要裝哪一個：一般網頁自動化選 @playwright/mcp，要 Chrome 深度除錯與效能分析選 chrome-devtools-mcp。

更新紀錄

• 2026-08-19：對照官方文件逐篇查證翻新，移除易腐內容，並收進「瀏覽器自動化與 MCP」系列

參考資料

• @modelcontextprotocol/server-puppeteer — GitHub（已封存）
• MCP servers 官方倉庫的 Archived 清單
• chrome-devtools-mcp — GitHub
• Puppeteer 官方文件
• Model Context Protocol — 官方文件
• Browser MCP 三選一比較
• @playwright/mcp 介紹
• Chrome DevTools MCP 介紹