Node Mantis

официальный

Автоматизация веб-сайтов: опишите задачу на обычном английском языке, и Node Mantis выполнит её на веб-странице в настоящем браузере и вернёт структурированные данные.

Что можно делать с Node Mantis MCP?

  • Выполняйте задачи на сайтах — Опишите цель простыми словами, а Node Mantis будет нажимать кнопки, вводить текст и заполнять формы в настоящем браузере.
  • Получайте структурированные данные — Укажите JSON Schema и получите результат задачи в виде данных, соответствующих этой структуре.
  • Читайте отдельную страницу — Используйте retrieve_data, чтобы извлечь нужную информацию с одной страницы, не внося изменений.
  • Управляйте длительными задачами — Проверяйте ход выполнения фоновой задачи или останавливайте её с помощью get_task и cancel_task.
  • Не передавайте секреты в чат — Ссылайтесь на сохранённые значения в формате <secret:NAME>, чтобы пароли и коды никогда не попадали в переписку.

Документация

MCP-сервер

Node Mantis включает сервер Model Context Protocol (MCP). Добавьте его в AI-ассистент с поддержкой MCP, например Claude Code, Claude Desktop, Cursor, VS Code или Codex, и ассистент сможет выполнять для вас задачи на веб-сайтах: он описывает задачу, Node Mantis выполняет её на сайте в настоящем браузере и возвращает результат в виде структурированных данных.

Добавив сервер в своего агента для программирования или ассистента, вы сможете:

  • Выполнять задачи на веб-сайтах. Опишите цель обычным языком, и Node Mantis выполнит её на сайте так, как это сделал бы реальный пользователь: нажмёт кнопки, введёт текст и заполнит формы, выпадающие списки и средства выбора даты.
  • Получать структурированные результаты. Передайте JSON Schema, и Node Mantis вернёт данные, соответствующие этой схеме.
  • Запускать длительные задачи в фоновом режиме. Задача, выполнение которой занимает несколько минут, продолжит выполняться, пока ассистент проверяет её состояние, сообщает о ходе выполнения или отменяет её.

Сервер входит в пакет node-mantis на npm и PyPI, поэтому устанавливать что-либо отдельно не нужно. Ассистент запускает его одной командой через 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, открываемый из настроек.
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, который хранится в ~/Library/Application Support/Claude/ в macOS и в %APPDATA%\Claude\ в Windows. Добавьте приведённую выше запись JSON, сохраните файл и перезапустите приложение.

Cursor

Добавьте приведённую выше запись JSON в ~/.cursor/mcp.json, чтобы использовать её во всех проектах, или в .cursor/mcp.json внутри одного проекта. Создайте файл, если его ещё нет.

VS Code

Вместо mcpServers VS Code использует servers. Добавьте это в .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"].

Python без uv

В приведённых выше примерах для 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>" }
    }
  }
}

Проверка работы

После перезапуска ассистент покажет node-mantis среди MCP-серверов с четырьмя инструментами. Затем попросите его выполнить задачу, например:

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

Работает так же, как run в SDK. Обязателен только параметр goal.

ПараметрТипПо умолчаниюОписание
goalstringобязательныйЧто нужно сделать. Опишите задачу обычным языком и укажите все детали, необходимые для её выполнения.
start_urlstringнетСтраница, которую нужно открыть первой. Если параметр не указан, задача сама найдёт путь к цели.
result_schemaobjectпроизвольный форматJSON Schema для возвращаемых данных. Результат будет содержать данные в указанной структуре.
effortlow | medium | high | xhighсреднийОбъём ресурсов, выделяемых на задачу. Более высокий уровень позволяет справляться со сложными страницами, но стоит дороже.
max_cost_usdnumberбез ограниченияБюджет в USD, проверяемый между шагами. На последнем шаге общие расходы могут превысить эту сумму.
max_stepsinteger30Максимальное число шагов до остановки задачи.
timeout_secondsinteger300Общий лимит времени для задачи.
secretsstring[]нетИмена секретных значений, которые задача может вводить. Каждое значение считывается из NODEMANTIS_SECRET_<NAME> в окружении сервера.
use_proxybooleanfalseНаправляет браузер через прокси, настроенный в окружении сервера.
show_browserbooleanfalseПоказывает окно браузера во время выполнения задачи.

retrieve_data

Работает так же, как retrieve в SDK. Используйте run_task вместо него, если для получения данных нужно нажимать кнопки, вводить текст или переходить по нескольким страницам.

ПараметрТипПо умолчаниюОписание
urlstringобязательныйСтраница для чтения.
promptstringобязательныйЧто нужно прочитать на странице.
result_schemaobjectпроизвольный форматJSON Schema, задающая структуру возвращаемых данных.
effortlow | medium | high | xhighсреднийОбъём ресурсов, выделяемых на чтение страницы.
use_proxybooleanfalseНаправляет браузер через прокси, настроенный в окружении сервера.
show_browserbooleanfalseПоказывает окно браузера во время чтения страницы.

get_task

ПараметрТипПо умолчаниюОписание
task_idstringобязательныйtask_id, возвращённый run_task или retrieve_data.
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."
}

Затем ассистент вызывает 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>, рядом с API-ключом в env. Ассистент передаёт только имена в secrets и ссылается на значение в описании задачи как <secret:NAME>. См. раздел Секреты.

Прокси

Чтобы направить браузер задачи через прокси, задайте NODEMANTIS_PROXY в окружении сервера и укажите в задаче use_proxy. Списки прокси и файлы работают так, как описано в разделе Настройка прокси.

Параметры сервера

Добавьте их после mcp в списке args.

ПараметрТипПо умолчаниюОписание
--wait-seconds <n>number45Сколько времени вызов инструмента ждёт выполнения задачи, прежде чем вернуть её идентификатор. Уменьшите значение, если ассистент прекращает ожидание вызова инструмента раньше.
--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-ключ.