Node Mantis
公式Web自動化:Webサイトでのタスクを平易な英語で説明すると、Node Mantisが実際のブラウザーでWebページを操作し、構造化データを返します。
Node Mantis MCPで何ができますか?
- ウェブサイトのタスクを実行 — 平易な英語で目標を伝えると、Node Mantisが実際のブラウザーでクリックや入力を行い、フォームを操作します。
- 構造化データを返す — JSON Schemaを指定すると、その形式に一致するデータとしてタスクの結果が返されます。
- 単一ページを読み取る —
retrieve_dataを使うと、何も変更せずに1つの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 のエントリをコマンドで追加するか、アシスタントの設定ファイルを編集すると、必要に応じてアシスタント自身がサーバーを起動します。手順は次の 3 つです。
- ダッシュボードから API キーをコピーします。
- 以下のエントリをアシスタントに追加します。追加先はアシスタントによって異なります。表と後続のセクションを参照してください。
- アシスタントを再起動し、動作を確認します。
ほとんどのアシスタントでは、同じ 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>" }
}
}
}
エントリは 3 つの部分で構成されています。
node-mantisは、アシスタントに表示されるサーバー名です。変更できます。commandとargsは、アシスタントがサーバーを起動する方法を指定します。Node.js 版または Python 版のどちらかを使ってください。どちらを使っても、アシスタントが利用できるツールは同じです。envには、サーバーの起動時にアシスタントから渡される設定が含まれます。プレースホルダーを API キーに置き換えてください。nodemantis configureを使ってキーをすでに保存している場合は、envを省略できます。
設定ファイルにすでに mcpServers セクションがある場合は、2 つ目の mcpServers を貼り付けるのではなく、既存のセクション内で他のエントリと並べて node-mantis エントリを追加してください。
| アシスタント | エントリの追加先 |
|---|---|
| Claude Code | ターミナルでコマンドを 1 つ実行します。 |
| Claude Desktop | 設定から開く claude_desktop_config.json。 |
| Cursor | すべてのプロジェクトで使う場合は ~/.cursor/mcp.json、1 つのプロジェクトで使う場合は .cursor/mcp.json。 |
| VS Code | ワークスペース内の .vscode/mcp.json。 |
| Codex | ターミナルでコマンドを 1 つ実行するか、~/.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
すべてのプロジェクトで使う場合は ~/.cursor/mcp.json に、1 つのプロジェクト内で使う場合は .cursor/mcp.json に、上記の 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 が 4 つのツールとともに表示されます。次に、たとえば以下のようなタスクを依頼します。
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 | ページを 1 つ開き、変更を加えずにデータを読み取ります。 |
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 | 上限なし | ステップ間で確認する USD の予算です。最終ステップでは、合計支出がこの金額を超える場合があります。 |
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 を受け取ります。すでに完了したタスクは変更されません。
長時間かかるタスク
ウェブサイト上のタスクは、アシスタントが 1 回のツール呼び出しで待てる時間を超えることがあります。そのため、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 のタスクでも、見つかった内容と理由が返されるため、アシスタントは目標を調整して再試行できます。完了したタスクは 1 時間保持されます。タスクは実行中のサーバーに属するため、アシスタントがサーバーを閉じると停止します。
シークレット
パスワードやワンタイムコードが会話を経由することはありません。各値をサーバーの環境に 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 キーが設定されていないと表示される。 サーバーの
envにNODEMANTIS_API_KEYを追加するか、nodemantis configureを一度実行してから、もう一度試してください。configureの後に再起動する必要はありません。 - 初回起動時にサーバーがタイムアウトする。 初回の
npx起動時には、パッケージがダウンロードされます。npm install -g node-mantisで一度インストールし、代わりにインストール済みのコマンドを起動してください。{ "mcpServers": { "node-mantis": { "command": "nodemantis", "args": ["mcp"] } } } - タスクを開始できない。
nodemantis doctorを実行して、インストール、ブラウザー、API キーを確認してください。