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) 서버가 포함되어 있습니다. Claude Code, Claude Desktop, Cursor, VS Code 또는 Codex와 같이 MCP를 지원하는 AI 어시스턴트에 추가하면, 어시스턴트가 웹사이트에서 작업을 수행할 수 있습니다. 어시스턴트가 작업을 설명하면 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 섹션이 있다면 두 번째 mcpServers을 붙여 넣는 대신, 그 안에 다른 항목과 나란히 node-mantis 항목을 추가하세요.

어시스턴트항목을 추가할 위치
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

설정을 연 다음 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는 mcpServers 대신 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"]로 설정합니다.

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상한 없음단계 사이에 확인하는 USD 예산입니다. 마지막 단계에서 총 지출이 이 금액을 초과할 수 있습니다.
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초 동안 기다립니다. 그 시간 안에 작업이 완료되면 호출이 결과를 반환합니다. 그렇지 않으면 task_id이 포함된 running 상태를 반환하고, 작업은 백그라운드에서 계속 실행됩니다.

{
  "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."
}

그런 다음 어시스턴트는 상태가 succeeded, failed 또는 cancelled이 될 때까지 해당 ID를 사용해 get_task을 호출합니다.

{
  "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 상태의 작업도 찾은 내용과 이유를 반환하므로, 어시스턴트가 목표를 조정해 다시 시도할 수 있습니다. 완료된 작업은 한 시간 동안 보관됩니다. 작업은 실행 중인 서버에 속하므로 어시스턴트가 서버를 닫으면 중지됩니다.

비밀 정보

비밀번호와 일회용 코드는 대화에 전달되지 않습니다. 각 값을 서버 환경에서 env의 API 키 옆에 NODEMANTIS_SECRET_<NAME>으로 설정합니다. 어시스턴트는 secrets에 이름만 전달하고, 목표에서는 값을 <secret:NAME>으로 참조합니다. 비밀 정보를 참조하세요.

프록시

작업의 브라우저 트래픽을 프록시로 보내려면 서버 환경에서 NODEMANTIS_PROXY을 설정하고 작업에 use_proxy을 전달하도록 합니다. 프록시 목록과 파일은 프록시 구성에 설명된 대로 작동합니다.

서버 옵션

args 목록에서 mcp 뒤에 다음 항목을 추가합니다.

매개변수유형기본값설명
--wait-seconds <n>number45도구 호출이 작업 ID를 반환하기 전까지 기다리는 시간입니다. 어시스턴트가 도구 호출을 더 일찍 포기한다면 값을 낮추세요.
--max-tasks <n>number4동시에 실행할 수 있는 작업 수입니다.
-H, --headedflagheadless도구 호출에서 show_browser를 설정하지 않는 한 모든 작업에서 브라우저 창을 표시합니다.

문제 해결

  • 어시스턴트가 API 키가 설정되지 않았다고 보고합니다. 서버의 env에 NODEMANTIS_API_KEY을 추가하거나 nodemantis configure를 한 번 실행한 다음 다시 시도하세요. configure 후에는 다시 시작할 필요가 없습니다.
  • 서버가 처음 시작할 때 시간 초과됩니다. 처음 npx을 실행하면 패키지가 다운로드됩니다. npm install -g node-mantis로 한 번 설치한 다음 설치된 명령을 시작하세요.
    {
      "mcpServers": {
        "node-mantis": {
          "command": "nodemantis",
          "args": ["mcp"]
        }
      }
    }
    
  • 작업을 시작하지 못합니다. nodemantis doctor을 실행해 설치, 브라우저 및 API 키를 확인하세요.