/unbrowse

name: unbrowse
description: Search and call websites through Unbrowse's hosted API or remote MCP, reuse indexed site tools, read pages, and learn missing routes in its cloud browser. Use for structured website tasks, and authenticated site access with Unbrowse.

Unbrowse

Use the hosted service at `https://unbrowse.ai`. Execution, indexed routes and website sessions stay server-side. This skill supplies operating guidance; signing in is OAuth, below.

Onboarding: sign in with OAuth

Sign-in is OAuth in the person's browser: an emailed sign-in link, then **Allow**. No password, and nothing to paste. Never ask the person for a token or key in chat.

Check first, then sign in only what is missing:

1. MCP: if `unbrowse_discover` is in this session's tool list, the MCP is signed in. 2. CLI: `npx unbrowse whoami`. Exit 0 means signed in. Exit 3 means not signed in.

Sign in the MCP (agent hosts):

claude mcp add --transport http unbrowse https://unbrowse.ai/mcp

{"mcpServers":{"unbrowse":{"url":"https://unbrowse.ai/mcp"}}}

The host runs the OAuth sign-in itself (in Claude Code: `/mcp`, pick `unbrowse`, Authenticate). Do not put a bearer header in the config; with one set, hosts skip OAuth. A URL in a config is not a signed-in session: until the host finishes OAuth, the Unbrowse tools are not listed.

Sign in the CLI:

npx skills add unbrowse-ai/unbrowse && npx unbrowse login

`unbrowse login` opens the sign-in page in the browser on this machine. The person enters their email, opens the link, presses **Allow**; the CLI prints `Signed in to https://unbrowse.ai (workspace ws_…)` and stores the token at `~/.config/unbrowse/cli.json` (mode 0600, refreshed automatically).

From an agent's shell (no terminal for the person): run `npx unbrowse login --no-open` in the background, give the person the `https://unbrowse.ai/authorize?…` link it prints, and wait for the `Signed in` line. The link returns to `127.0.0.1` on this machine, so the person must open it in a browser on the same machine. On a remote or headless box, run `npx unbrowse login --device` and approve the code it shows from any device, or use an API key (below). Any other command run with no sign-in starts the same browser sign-in when it has a terminal; without one it exits 3 and asks for `unbrowse login`.

Then the first call: `npx unbrowse run 'top stories on hacker news'`. The site requests go from the person's own IP by default; `--from-unbrowse` sends them from Unbrowse instead.

`npx unbrowse mcp` (a stdio MCP for hosts that need one) uses the CLI sign-in; `unbrowse mcp add` registers it with Claude Code and Codex, so they run on that one sign-in. The other way: with no CLI sign-in, the CLI can use Claude Code's own Unbrowse MCP sign-in, but only for a server added at `https://unbrowse.ai/api/mcp`. A token for `https://unbrowse.ai/mcp` (the URL the plugins and the setup above use) does not work on the REST API, so in that case run `unbrowse login`. No token is ever written into an MCP config.

For automation and CI without a browser, set `UNBROWSE_API_KEY` from the caller's secret manager (create a key in the signed-in console at https://unbrowse.ai/app). Never put keys into committed config, prompts, command arguments or logs.

CLI and SDK: https://github.com/unbrowse-ai/unbrowse

Host plugins

Packaged installs that bundle this skill, connect Unbrowse and redirect the host's own browser to it (https://github.com/unbrowse-ai/unbrowse/tree/main/plugins):

• Claude Code: `claude plugin marketplace add unbrowse-ai/unbrowse`, then `claude plugin install unbrowse@unbrowse`.
• Codex: `codex plugin marketplace add unbrowse-ai/unbrowse`, then `codex plugin add unbrowse@unbrowse`; set `web_search = "disabled"` to drop built-in search.
• Grok Build: `grok plugin install unbrowse-ai/unbrowse#plugins/grok-build --trust`.
• OpenClaw (`@unbrowse/openclaw`), Hermes (`plugins/hermes`), elizaOS (`@unbrowse/plugin-unbrowse`): native tools or actions over the same MCP.

Hosts that need a stdio server can run `npx unbrowse mcp`; it serves the same `unbrowse_…` tool names. With a plugin installed, built-in web fetch, web search and browser navigation to non-local URLs are refused with a pointer to the matching Unbrowse tool; `UNBROWSE_ALLOW_BUILTIN_BROWSER=1` lifts that for a session.

Choose the interface

• MCP: discovery, runs, page reading, cloud browsing, indexing and saved-login requests. These names are MCP tools; the CLI has a command for each (below).
• CLI: `unbrowse discover`, `run`, `inspect`, `resume`, `scrape <url>` (one page as markdown), `index <url>` (teach a site; `index status`), `registry`, `site`, `whoami`. `scrape` and `index` need CLI 12.2.0 or later. `unbrowse run` never drives a website in a browser (the only browser it opens is the first-use sign-in). From CLI 12.5.0 every MCP tool has a command: `unbrowse map <url>`, `sites [site]`, `forget`, `connect [app]`, `credits`, the cloud browser `unbrowse browse open <url>` / `browse snapshot <id>` / `browse act <id> click e1` / `browse finish <id>` / `browse close <id>`, `credentials list|request|status`, `replay list|search|get|timeline|ask`; `unbrowse tool <name>` calls any other listed tool, such as a learned site tool. There is no `unbrowse install`. `unbrowse help` describes the installed version.
• SDK: REST integration and scripting. Consult the public SDK docs for its supported methods; MCP tools and REST methods are not interchangeable names.

Core MCP tools: `unbrowse_discover`, `unbrowse_run`, `unbrowse_inspect`, `unbrowse_resume`, `unbrowse_cancel`, `unbrowse_scrape`, `unbrowse_map`, `unbrowse_sites`, `unbrowse_usage`, `unbrowse_credits`, `unbrowse_forget`, `unbrowse_learn`, `unbrowse_index`, `unbrowse_index_status`, `unbrowse_credentials_list`, `unbrowse_credentials_request`, `unbrowse_credentials_status`, `unbrowse_connect` (connect an app's own MCP server, such as Linear, Notion or GitHub, so its tools run as the p