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
也可以通过 uv 使用 Python 启动:
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。 |
| 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
打开“设置”,然后依次选择“开发者”和“编辑配置”。这会打开 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 密钥。