unbrowse

Files (2)

• SKILL.md
• tools.json · references/

SKILL.md (first lines)

# 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):

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

```json
{"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:

```sh
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 person: an app with sign-in returns a link the person opens), `unbrowse_import_mcps` (bring the MCP servers this agent already has into Unbrowse, below), and the cloud browser `unbrowse_browse_open`, `unbrowse_browse_snapshot`, `unbrowse_browse_act`, `unbrowse_browse_finish`, `unbrowse_browse_close`.

[references/tools.json](references/tools.json) contains the exported core MCP input schemas. The connected server's `tools/list` is authoritative: it also includes dynamic tools available to this user's workspace. Never invent a capability ID or input schema.

## Execute a task

1. Discover with `unbrowse_discover {query}`. Inspect returned inputs, choices and hints. Prefer a healthy matching capability; `warm` means HTTP replay, `rendered` needs rendering. Check `unbrowse_sites` for saved session and login state when relevant. Public tools carry `version`, the Unbrowse version that generated them (YYYY.MM.DD); among equal matches the newest comes first, and `minVersion` leaves older ones out.
2. Call the selected tool with its listed schema, or `unbrowse_run {capability, input}`. A natural-language `task` can route when no ID was selected. Use a stable `idempotencyKey` for the same intended mutation. For a large answer pass `select` (MCP run tools, `unbrowse_resume`, `unbrowse_inspect`, `POST /api/v1/runs`): paths like `["results[].{id,title,price}", "total"]`. It narrows only what comes back, after verification; billing is unchanged. Results over 40,000 characters are shortened (`truncated: true`); `selectMissing` lists paths that matched nothing.
3. Inspect the returned status and actual result. `input_required` means answer the open requirements on the **same** run: `unbrowse_resume {runId, answers:{field:value}}`. For a choice, pass the listed option's value. Preserve revision checks when supplied.
4. `no_capability` means no reusable route matched. Follow `result.next`: `tool` is `unbrowse_index` (`POST /api/v1/index`, then `GET /api/v1/index/{jobId}`; CLI `unbrowse index <url>`). To answer now, read the page instead: `unbrowse_scrape` (CLI `unbrowse scrape <url>`). Call `unbrowse_browse_open` only when that name is in this session's tool list (from a shell: `unbrowse browse open <url>`, CLI 12.5.0+). Do not POST `/api/v1/browse/open`. It is not a route. Report unsupported or blocked sites honestly.
5. Only report completion from a verified result. `outcome_unknown` means a change may have occurred: inspect the effect receipt and destination before retrying. Cancellation stops future dispatches; it does not undo completed effects.

Do not infer business success from HTTP 200, tool transport success, a screenshot, or a generated plan. Do not promise universal coverage or browserless execution on every first request. Obtain the user's authorization for posting, sending, purchasing or other external writes.

## Unbrowse a URL

When the person names a site:

1. If `unbrowse_discover` is not in this session's tool list, the MCP is not signed in. Stop. Name the configured MCP URL. A remote MCP needs the host's own OAuth; with the CLI signed in, `npx unbrowse mcp add` gives the host a server on that sign-in instead (it takes effect in a new session).
2. Look the host up (`unbrowse_sites`, or CLI `unbrowse site <host>`). Tools already compiled: use one. Stop.
3. No tools: `unbrowse_index {url, focus}` or `POST /api/v1/index`. Poll `unbrowse_index_status` or `GET /api/v1/index/{jobId}`.
4. `status: failed` and `error.code: model_unavailable`: the indexing model is out of credit. Report the job id and the message. Do not browse instead, and do not start the same job again in a loop.
5. `status: done` with `indexed: 0` means nothing was learned. Say so. `indexed > 0` means call one tool and check the result.

A 202 from `/api/v1/index` is a job id, not a compiled tool.

## A site's tools over plain HTTP

Each compiled site is also a REST API, for code rather than an agent session:

- `GET https://unbrowse.ai/api/v1/sites/<host>/openapi.json`: OpenAPI 3.1, one operation per tool, typed inputs, an `example` input it was verified with, every status and header. No key needed to read.
- `POST https://unbrowse.ai/api/v1/sites/<host>/call/<tool>` with the tool's inputs as the JSON body and `Authorization: Bearer <key>`. Options: `x-unbrowse-deadline-ms`, `Idempotency-Key`, `select`. `202` means `input_required`; `504 run_timeout` gives a `runId` to poll; `409 tool_quarantined` means use another tool.
- SDK: `new Unbrowse().callTool(host, tool, input)`.

Contract and examples: https://unbrowse.ai/docs/site-apis.md

## Read or learn a site

Prefer `unbrowse_discover` and a matching tool or `unbrowse_run` for structured data and site tasks. `unbrowse_scrape {url}` is a **last resort for static pages and documents**, only when no suitable API or learned tool is available. A PDF, .docx, .xls or .xlsx URL comes back as extracted markdown text (`metadata.pages` for PDFs; spreadsheets preserve sheet names, rows and formatted values). `metadata.truncated` marks bounded extraction; `formats: ["raw"]` returns the exact document bytes as base64; `unbrowse_map {url}` finds same-site URLs. A known URL or scrape's rendering support does not make it the default. For dynamic content, search, pagination or interaction with no matching route, use `unbrowse_index` or the available cloud browser tools to learn and replay the site's API:

1. `unbrowse_browse_open {url,task}` returns the page and element refs.
2. Use `unbrowse_browse_act` with the latest refs. For ordinary inputs, include a meaningful `name` such as `date` or `query`; exercise every filter the task needs. Refresh the snapshot after page changes.
3. Use `unbrowse_browse_finish {sessionId}` to return the final page and compile observed routes. Two sessions with different inputs help identify reusable parameters. Check `learnError` and `newTool`; browsing success alone does not prove a reusable route exists.
4. Close sessions when finished. `unbrowse_browse_close` still indexes unless `discard:true`.

To cover a whole site ahead of need, `unbrowse_index {url, focus?, maxCapabilities?}` starts a background job: Unbrowse's own agent performs the site's core read-only capabilities, proves each with a browserless replay and adds them to your tools. Follow it with `unbrowse_index_status {jobId}`. `maxCapabilities` caps every tool the job indexes (declared, sitemap page types and recorded flows together). A `focus` keeps only sitemap page types that match it, and none when it names flows such as paging, page size, filters or search. Query keys in the start URL (`?page=0&pageSize=100`) become the tool's inputs. `stoppedReason` says why a job ended. The time budget is extended once, by half, while tools are still being proven.

An existing HAR pair can be sent through `unbrowse_learn`. Only submit recordings the user authorized; HARs can contain private data. Private and loopback destinations are refused by the hosted service.

## Bring the agent's MCP servers

When the person wants their existing MCP servers in Unbrowse (one sign-in, every agent gets them), import them instead of re-adding each by hand.

- From a terminal: `npx unbrowse mcps` lists the servers in this machine's agent configs (Claude Code, Claude Desktop, Cursor, Codex, VS Code, Windsurf, Gemini, Zed); `npx unbrowse mcps import` imports them (`--dry-run` shows the plan). Keys in those configs stay on the machine unless the person adds `--with-keys`.
- As an MCP tool: read your host's MCP config yourself and call `unbrowse_import_mcps {servers:[{name, url} | {name, command, args}]}`. Never pass keys, headers or env values; `dryRun: true` shows the plan.
- Remote servers connect by address. A local (stdio) server cannot run in Unbrowse's cloud: when the catalog has the same app hosted, that is connected instead; otherwise it is `local_only` and stays in the agent. `sign_in` and `key` rows carry the link the person opens. Show them the plan before importing.

## Website sign-in

From unbrowse-ai/unbrowse, MIT.

More from unbrowse-ai/unbrowse