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 設定;助理需要時會自行啟動伺服器。共有三個步驟:
大多數助理都會讀取相同的 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 Desktop | claude_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。
| 參數 | 類型 | 預設值 | 說明 |
|---|---|---|---|
goal | string | 必填 | 要完成的事項,以白話描述,並包含完成工作所需的所有細節。 |
start_url | string | 無 | 首先開啟的頁面。若未提供,工作會根據目標自行尋找路徑。 |
result_schema | object | 自由格式 | 要傳回資料的 JSON Schema。結果會以符合該結構的資料傳回。 |
effort | low | medium | high | xhigh | 中 | 要投入的能力。較高的投入程度可處理更困難的頁面,但成本也較高。 |
max_cost_usd | number | 無上限 | 在步驟之間檢查的美元預算。最後一步可能會使總支出超過此金額。 |
max_steps | integer | 30 | 工作停止前的最大步驟數。 |
timeout_seconds | integer | 300 | 工作的總時間限制。 |
secrets | string[] | 無 | 工作可輸入的私密值名稱。每個值都會從伺服器環境中的 NODEMANTIS_SECRET_<NAME> 讀取。 |
use_proxy | boolean | false | 透過伺服器環境中設定的代理伺服器轉送瀏覽器流量。 |
show_browser | boolean | false | 工作執行時顯示瀏覽器視窗。 |
retrieve_data
功能與 SDK 中的 retrieve 相同。若要取得資料需要點擊、輸入或瀏覽多個頁面,請改用 run_task。
| 參數 | 類型 | 預設值 | 說明 |
|---|---|---|---|
url | string | 必填 | 要讀取的頁面。 |
prompt | string | 必填 | 要從頁面讀取的內容。 |
result_schema | object | 自由格式 | 傳回資料結構的 JSON Schema。 |
effort | low | medium | high | xhigh | 中 | 讀取頁面時要投入的能力。 |
use_proxy | boolean | false | 透過伺服器環境中設定的代理伺服器轉送瀏覽器流量。 |
show_browser | boolean | false | 讀取頁面時顯示瀏覽器視窗。 |
get_task
| 參數 | 類型 | 預設值 | 說明 |
|---|---|---|---|
task_id | string | 必填 | run_task 或 retrieve_data 傳回的 task_id。 |
wait_seconds | integer | 45 | 等待工作完成的時間上限,之後才回覆。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> | number | 45 | 工具呼叫等待工作多久才傳回工作 ID。如果助理較早放棄工具呼叫,請調低此值。 |
--max-tasks <n> | number | 4 | 可同時執行的工作數量。 |
-H, --headed | flag | headless | 除非工具呼叫設定 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 金鑰。