Node Mantis

官方

網頁自動化:用淺白英文描述網站任務,Node Mantis 會在真實瀏覽器中操作網頁並回傳結構化資料。

你可以用 Node Mantis MCP 做什麼?

  • 執行網站任務 — 提供淺顯易懂的目標,Node Mantis 就會在真實瀏覽器中點擊、輸入並處理表單。
  • 傳回結構化資料 — 提供 JSON Schema,即可取得符合該結構的任務結果資料。
  • 讀取單一頁面 — 使用 retrieve_data 從單一 URL 擷取特定資訊,不會變更任何內容。
  • 管理長時間執行的任務 — 使用 get_task 查看進度,或使用 cancel_task 停止背景任務。
  • 避免在聊天中透露機密 — 以 <secret:NAME> 引用已儲存的值,讓密碼和驗證碼不會出現在對話中。

文件

MCP 伺服器

Node Mantis 包含 Model Context Protocol (MCP) 伺服器。將它新增至支援 MCP 的 AI 助理,例如 Claude Code、Claude Desktop、Cursor、VS Code 或 Codex,助理就能替你在網站上執行工作:你描述工作內容,Node Mantis 會在真實瀏覽器中操作網站,並以結構化資料傳回結果。

將伺服器新增至你的程式碼代理或助理後,你就能:

  • 執行網站工作。 用白話描述目標,Node Mantis 就會像真正的使用者一樣操作網站:點擊、輸入,以及處理表單、下拉式選單和日期選擇器。
  • 取得結構化結果。 提供 JSON Schema,Node Mantis 就會傳回符合該結構的資料。
  • 在背景執行長時間工作。 需要數分鐘的工作會持續執行,助理可以查看進度、回報進度或取消工作。

伺服器是 npm 和 PyPI 上 node-mantis 套件的一部分,因此不需要另外安裝。助理會透過 Node.js 使用一個命令啟動伺服器:

npx -y node-mantis mcp

或透過 Python 搭配 uv:

uvx node-mantis mcp

兩種方式都會提供相同的工具給助理。你需要 Node.js 或 Python、Google Chrome,以及從 儀表板取得的 API 金鑰。如果尚未安裝 Chrome,第一個工作會下載 Chrome for Testing。

新增至你的助理

每個助理都會在設定中保留一份 MCP 伺服器清單。你可以透過命令或編輯助理的設定檔,新增一筆 Node Mantis 設定;助理需要時會自行啟動伺服器。共有三個步驟:

  1. 從儀表板複製 API 金鑰。
  2. 將下方的設定新增至助理。設定位置依助理而異,請參閱表格和後續章節。
  3. 重新啟動助理,並確認運作正常。

大多數助理都會讀取相同的 JSON 設定。使用 Node.js:

{
  "mcpServers": {
    "node-mantis": {
      "command": "npx",
      "args": ["-y", "node-mantis", "mcp"],
      "env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
    }
  }
}

使用 Python:

{
  "mcpServers": {
    "node-mantis": {
      "command": "uvx",
      "args": ["node-mantis", "mcp"],
      "env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
    }
  }
}

這筆設定包含三個部分:

  • node-mantis 是助理顯示的伺服器名稱。你可以變更它。
  • command 和 args 是助理啟動伺服器的方式。使用 Node.js 或 Python 版本皆可;兩者都會提供相同的工具給助理。
  • env 存放助理啟動伺服器時傳遞給伺服器的設定。請將佔位文字替換為你的 API 金鑰。如果你已透過 nodemantis configure 儲存金鑰,就可以省略 env。

如果設定檔中已有 mcpServers 區段,請將 node-mantis 設定新增至其中,與其他項目並列,而不要再貼上一個 mcpServers。

助理設定位置
Claude Code在終端機執行一個命令。
Claude Desktopclaude_desktop_config.json,從 Settings 開啟。
Cursor~/.cursor/mcp.json,適用於所有專案;或 .cursor/mcp.json,適用於單一專案。
VS Code工作區中的 .vscode/mcp.json。
Codex在終端機執行一個命令,或使用 ~/.codex/config.toml。

Claude Code

在終端機執行以下其中一個命令。使用 Node.js:

claude mcp add node-mantis -e NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- npx -y node-mantis mcp

使用 Python:

claude mcp add node-mantis -e NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- uvx node-mantis mcp

接著 claude mcp list 會顯示 node-mantis 已連線。

Claude Desktop

開啟 Settings,接著選擇 Developer,再選擇 Edit Config。這會開啟 claude_desktop_config.json,在 macOS 上位於 ~/Library/Application Support/Claude/,在 Windows 上則位於 %APPDATA%\Claude\。新增上方的 JSON 設定、儲存檔案,然後重新啟動應用程式。

Cursor

將上方的 JSON 設定新增至 ~/.cursor/mcp.json,即可用於所有專案;或新增至單一專案中的 .cursor/mcp.json。如果檔案不存在,請建立檔案。

VS Code

VS Code 使用 servers,而非 mcpServers。將以下內容新增至工作區中的 .vscode/mcp.json:

{
  "servers": {
    "node-mantis": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "node-mantis", "mcp"],
      "env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
    }
  }
}

使用 Python 時,將 command 設為 uvx,並將 args 設為 ["node-mantis", "mcp"]。

Codex

在終端機執行以下其中一個命令。使用 Node.js:

codex mcp add node-mantis --env NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- npx -y node-mantis mcp

使用 Python:

codex mcp add node-mantis --env NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- uvx node-mantis mcp

或者編輯 ~/.codex/config.toml。較長的啟動時間限制可讓首次啟動有足夠時間下載套件:

[mcp_servers.node-mantis]
command = "npx"
args = ["-y", "node-mantis", "mcp"]
startup_timeout_sec = 60

[mcp_servers.node-mantis.env]
NODEMANTIS_API_KEY = "sk_live_<copy-from-dashboard>"

使用 Python 時,將 command 設為 "uvx",並將 args 設為 ["node-mantis", "mcp"]。

不使用 uv 的 Python

上方的 Python 範例使用 uv,首次使用時會從 PyPI 取得套件。不使用 uv 時,請先透過 python -m pip install node-mantis 安裝套件一次,並使用 nodemantis 作為命令,將 mcp 作為唯一引數:

{
  "mcpServers": {
    "node-mantis": {
      "command": "nodemantis",
      "args": ["mcp"],
      "env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
    }
  }
}

確認運作正常

重新啟動後,助理會在 MCP 伺服器清單中列出 node-mantis,並提供四個工具。接著請它執行一項工作,例如:

Use Node Mantis to open https://sandbox.nodemantis.com and tell me the title and price of the first book.

助理會呼叫 run_task,並根據工作找到的內容作答。如果沒有,請參閱疑難排解。

Windows

如果助理無法直接啟動 npx,請透過 cmd 執行:

{
  "mcpServers": {
    "node-mantis": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "node-mantis", "mcp"],
      "env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
    }
  }
}

工具

工具說明
run_task根據白話描述的目標,在網站上執行工作:瀏覽、點擊、輸入、填寫表單並讀取結果。
retrieve_data開啟單一頁面並讀取資料,不對頁面進行任何變更。
get_task等待工作並傳回其狀態、最新進度和結果。
cancel_task停止執行中的工作並關閉其瀏覽器。

每項工作都會在全新的瀏覽器工作階段中執行,不會儲存登入狀態,且工作結束時工作階段會關閉。

run_task

功能與 SDK 中的 run 相同。只需要 goal。

參數類型預設值說明
goalstring必填要完成的事項,以白話描述,並包含完成工作所需的所有細節。
start_urlstring無首先開啟的頁面。若未提供,工作會根據目標自行尋找路徑。
result_schemaobject自由格式要傳回資料的 JSON Schema。結果會以符合該結構的資料傳回。
effortlow | medium | high | xhigh中要投入的能力。較高的投入程度可處理更困難的頁面,但成本也較高。
max_cost_usdnumber無上限在步驟之間檢查的美元預算。最後一步可能會使總支出超過此金額。
max_stepsinteger30工作停止前的最大步驟數。
timeout_secondsinteger300工作的總時間限制。
secretsstring[]無工作可輸入的私密值名稱。每個值都會從伺服器環境中的 NODEMANTIS_SECRET_<NAME> 讀取。
use_proxybooleanfalse透過伺服器環境中設定的代理伺服器轉送瀏覽器流量。
show_browserbooleanfalse工作執行時顯示瀏覽器視窗。

retrieve_data

功能與 SDK 中的 retrieve 相同。若要取得資料需要點擊、輸入或瀏覽多個頁面,請改用 run_task。

參數類型預設值說明
urlstring必填要讀取的頁面。
promptstring必填要從頁面讀取的內容。
result_schemaobject自由格式傳回資料結構的 JSON Schema。
effortlow | medium | high | xhigh中讀取頁面時要投入的能力。
use_proxybooleanfalse透過伺服器環境中設定的代理伺服器轉送瀏覽器流量。
show_browserbooleanfalse讀取頁面時顯示瀏覽器視窗。

get_task

參數類型預設值說明
task_idstring必填run_task 或 retrieve_data 傳回的 task_id。
wait_secondsinteger45等待工作完成的時間上限,之後才回覆。0 表示立即回覆。

cancel_task

接受一個 task_id。已完成的工作不會受到影響。

長時間工作

網站工作可能比助理願意等待單次工具呼叫的時間更久。因此,run_task 和 retrieve_data 最多會等待 45 秒。如果工作在這段時間內完成,呼叫就會傳回結果;否則會傳回狀態 running 和一個 task_id,工作則會在背景繼續執行:

{
  "task_id": "task_6f0c2a54-8f0e-4f0a-9d2b-2f6c1f1f8a10",
  "tool": "run_task",
  "status": "running",
  "elapsed_seconds": 45,
  "progress": {
    "step": 6,
    "max_steps": 30,
    "message": "Step 6/30: The cart shows one book. — click(\"Checkout\")"
  },
  "next_step": "Still running. Call get_task with task_id \"task_6f0c2a54-8f0e-4f0a-9d2b-2f6c1f1f8a10\" to wait for the result, or cancel_task to stop it."
}

接著助理會使用該 ID 呼叫 get_task,直到狀態變為 succeeded、failed 或 cancelled:

{
  "task_id": "task_6f0c2a54-8f0e-4f0a-9d2b-2f6c1f1f8a10",
  "tool": "run_task",
  "status": "succeeded",
  "elapsed_seconds": 71,
  "result": {
    "ok": true,
    "reason": "Added the book to the cart and read the cart.",
    "value": { "title": "Journey to the Center of the Earth", "quantity": 1 },
    "steps": 9,
    "cost_usd": 0.04,
    "trace_id": "op_1794979105280_5c3e8996"
  }
}

failed 工作仍會傳回找到的內容及原因,讓助理調整目標後再試一次。已完成的工作會保留一小時。工作隸屬於正在執行的伺服器:助理關閉伺服器時,工作也會停止。

密鑰

密碼和一次性驗證碼絕不會經過對話傳遞。請在伺服器環境中將每個值設為 NODEMANTIS_SECRET_<NAME>,並與 env 中的 API 金鑰放在一起。助理只會傳遞 secrets 中的名稱,並在目標中以 <secret:NAME> 參照值。請參閱密鑰。

代理伺服器

若要透過代理伺服器傳送工作的瀏覽器流量,請在伺服器環境中設定 NODEMANTIS_PROXY,並讓工作傳遞 use_proxy。代理伺服器清單和檔案的運作方式如代理伺服器設定所述。

伺服器選項

將以下選項新增至 args 清單中的 mcp 之後。

參數類型預設值說明
--wait-seconds <n>number45工具呼叫等待工作多久才傳回工作 ID。如果助理較早放棄工具呼叫,請調低此值。
--max-tasks <n>number4可同時執行的工作數量。
-H, --headedflagheadless除非工具呼叫設定 show_browser,否則每項工作都會顯示瀏覽器視窗。

疑難排解

  • 助理回報尚未設定 API 金鑰。 將 NODEMANTIS_API_KEY 新增至伺服器的 env,或執行一次 nodemantis configure,然後再試一次。設定 configure 後不需要重新啟動。
  • 伺服器首次啟動時逾時。 首次啟動 npx 時會下載套件。請先使用 npm install -g node-mantis 安裝一次,再啟動已安裝的命令:
    {
      "mcpServers": {
        "node-mantis": {
          "command": "nodemantis",
          "args": ["mcp"]
        }
      }
    }
    
  • 工作無法啟動。 執行 nodemantis doctor,檢查安裝、瀏覽器和 API 金鑰。