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 添加一项配置;助手需要时会自行启动服务器。分为三个步骤:

  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 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。

参数类型默认值说明
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 密钥。