# HumanJS MCP server

> Lets an AI client drive a Playwright browser with human-like mouse, typing, and scrolling, and record sessions as video or tests.

- Repository: https://github.com/totigm/humanjs
- Page: https://hostedmcp.org/servers/totigm/humanjs
- Transport: stdio
- Stars: 28
- License: MIT

## Install

### Claude Code

```sh
claude mcp add humanjs -- npx -y @humanjs/mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "humanjs": {
      "command": "npx",
      "args": [
        "-y",
        "@humanjs/mcp"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "humanjs": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@humanjs/mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"humanjs","type":"stdio","command":"npx","args":["-y","@humanjs/mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "humanjs": {
      "command": "npx",
      "args": [
        "-y",
        "@humanjs/mcp"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add humanjs -- npx -y @humanjs/mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.humanjs]
command = "npx"
args = ["-y", "@humanjs/mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user humanjs npx -- -y @humanjs/mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "humanjs": {
      "command": "npx",
      "args": [
        "-y",
        "@humanjs/mcp"
      ]
    }
  }
}
```

## Tools (38)

- `human_goto`: Navigates the session's page to a URL. Plugins observe a "goto" action. Equivalent to a user typing a URL in the address bar.
- `human_click`: Moves the cursor to the target along a humanized Bezier path and clicks. Target is a selector OR x/y coordinates — use coordinates for icon-only buttons or anything with no clean selector that you can see in a screenshot.
- `human_rightClick`: Right-clicks the target to open a context menu. Same motion as human_click; only the dispatched button differs. Target is a selector OR x/y coordinates.
- `human_doubleClick`: Double-clicks the target — same humanized motion as human_click, but two presses within the OS double-click window. Use for things that open/activate on double-click (list rows, file items, editable cells). Target is a selector OR x/y coordinates.
- `human_hover`: Moves the cursor to an element and settles on it (no click), letting hover-triggered UI fire — tooltips, dropdowns. Element-bound only; for positioning the cursor at coordinates without an element, use human_move.
- `human_move`: Moves the cursor to a target along a Bezier path with no click and no settle dwell — pure positioning. Useful before a keyboard action, for canvas work, or cinematic beats. Target is a selector OR x/y coordinates.
- `human_drag`: Drags from one location to another — cursor → source, mousedown, source → destination, mouseup, all humanized. Each endpoint is a selector OR x/y coordinates (use coordinates for sliders, canvas, SVG handles).
- `human_type`: Clicks the element to focus it, then types with humanized per-key rhythm. The current personality controls speed, typo probability, and corrections (HUMANJS_PERSONALITY / human_set_personality). If this types into a search/filter, the results re-render (often debounced) — use a specific selector for the result, as the list shifts as it filters.
- `human_paste`: Inserts text in one shot (the Cmd-V semantic) — focuses the field, then sets the whole value via insertText with no per-key timing. Use for long strings where humanized typing would be slow. Does not fire the page paste event.
- `human_clear`: Clears a text field (input/textarea/contenteditable) with a real keyboard gesture — click to focus, select-all, then delete — firing the input events the page expects. Use before human_type when you need to replace an existing value rather than append to it.
- `human_selectText`: Selects (highlights) text inside an element — moves the cursor to it, then selects. By default selects all of the element’s text; pass `text` to select just that substring (found inside the element, whitespace-tolerant, first match; falls back to the whole element if not found). Use before copying, replacing, or triggering a highlight menu.
- `human_check`: Ticks a checkbox or radio — moves the cursor to it and clicks, but only if it is not already checked (a real user does not re-click a ticked box). Verifies the resulting state. Pass the checkbox/radio input itself (or a [role=checkbox]) — not a wrapping <label> — so the current state can be read and the click stays idempotent.
- `human_uncheck`: Unticks a checkbox — humanized click only if currently checked. Radios cannot be unchecked by clicking (select a different option instead). Pass the checkbox input itself (or a [role=checkbox]) — not a wrapping <label> — so its state can be read and the click stays idempotent.
- `human_selectOption`: Chooses option(s) in a native <select> — moves the cursor to the dropdown, then sets the value (native selects open an OS menu automation can't drive, so the value is set programmatically, firing change/input). For custom DOM dropdowns, use human_click on the rendered options instead. Match by value(s); pass one string or an array for multi-selects.
- `human_upload`: Attaches file(s) to a file input — moves the cursor to the control, then sets the files (never opens the OS dialog, which would hang). For safety, files are read by basename from HUMANJS_UPLOAD_DIR (default: the server working dir) — subdirectories, "../", and absolute paths are rejected, so the agent can't read and exfiltrate arbitrary local files. Pass the <input type="file"> selector and the filename(s).
- `human_press`: Presses a single key (Enter, Tab, Escape, ArrowDown, …) or a chord (Mod+S, Cmd+Shift+P, Ctrl+C). "Mod" maps to Meta on Mac and Control elsewhere. Dispatches against focus — does not move the cursor; compose with human_click/human_move when you need both.
- `human_scroll`: Scrolls the page or a container with a natural velocity profile. Default scrolls one viewport down. Use `target` for presets ("natural"/"end"/"top") or an element selector to scroll into view; `by` for a relative pixel delta; `to` for an absolute position.
- `human_read`: Dwells as if reading the target — pause time derived from word count and the personality's reading speed, with a visible cursor scan across the text. Models the "user pauses to read" beat. Provide a selector OR literal text.
- `human_screenshot`: Captures the current page (or a specific element if `selector` is given) as a PNG and returns it as image content the AI can view directly. Pass `filename` to also save it to disk (HUMANJS_OUTPUT_DIR); omit it for an ephemeral look-at-the-page capture.
- `human_page_text`: Returns the page's visible text (document.body.innerText). The fastest way to understand what's on screen without parsing HTML — prefer this over human_get_html unless you need element structure or attributes.
- `human_outline`: Returns a compact accessibility-tree outline of the page (or a region) — every interactive element and landmark by its ARIA role + accessible name, as YAML (e.g. `- button "Sign in"`, `- textbox "Email"`). The most token-efficient way to see what is actionable and pick a selector: the names map directly to getByRole / accessible-name selectors. Prefer this over human_get_html for "what can I click or fill"; use human_screenshot when you need the visual layout.
- `human_get_text`: Returns the innerText of the first element matching `selector` — a specific label, price, status, or message. Set `all` to read every match instead, e.g. every row's title in a table; a sweep reports each match in document order, including ones that are not currently visible.
- `human_get_attribute`: Returns the value of an attribute on the first element matching `selector` (or reports it is absent). Handy for reading aria-label, data-*, href, value, disabled state, etc. — often how you confirm an icon-only button's purpose. Set `all` to collect the attribute across every match, which is the compact way to extract every image source or link target on a page.
- `human_get_html`: Returns the outerHTML of the first element matching `selector` — the element plus its children, including its own attributes (class, aria-label, etc.). The go-to tool for discovering the real selector of a control with no obvious text. Target a specific region; full-page HTML is large. Set `all` to dump every match, but prefer human_get_attribute with `all` when you only need one attribute from each — it returns the same information for a fraction of the tokens.
- `human_console_messages`: Returns console output and uncaught page errors captured for this session, newest last. Capture starts when the session is created, so this covers everything since — including errors thrown during the first page load. The go-to tool when something looks wrong on the page but the screenshot doesn't explain why: CORS rejections, failed asset loads, and thrown exceptions all surface here and nowhere else.
- `human_network_requests`: Returns network responses captured for this session, newest last, with method, URL, HTTP status and round-trip time. Requests that never got a response (DNS failure, blocked by CORS, aborted) are included with the browser's failure reason instead of a status. Use `onlyFailures` to answer "what broke?" in one call — it covers both 4xx/5xx responses and requests that never completed.
- `human_start_recording`: Begins recording the session. Every humanized action until human_stop_recording is captured (frames + action timeline). The visible cursor is in the video. One recording per session at a time. For a natural-looking take: explore the flow first to find correct selectors, then dispatch the whole run — start_recording + every action + stop_recording — in a SINGLE turn (one batch of tool calls), so there are no model-thinking pauses between actions to leave dead air in the video.
- `human_stop_recording`: Stops the active recording and writes it to one or more files in HUMANJS_OUTPUT_DIR. Each filename's extension picks its format: .mp4/.webm = video, .gif = animated gif, .json = action timeline, .ts = runnable HumanJS script, .spec.ts/.test.ts = @playwright/test spec (humanized, with derived assertions). Pass several to export the same recording multiple ways, e.g. ["demo.mp4", "checkout.spec.ts"] for a video plus a ready-to-commit test. Path components are rejected for safety.
- `human_create_session`: Opens a new isolated session (its own browser context, cookies, viewport) under the given ID. Only needed for parallel browsers — for a single browser, just omit the session arg on other tools and the default session is used.
- `human_close_session`: Closes a session and frees its browser context. Closing the default session is allowed — it will be recreated lazily on the next call.
- `human_list_sessions`: Lists every currently-open session with its personality. Use to orient before acting on a specific session.
- `human_set_personality`: Changes the humanization personality for a session at runtime. Pass a preset, or a blend of two presets (e.g. mostly careful with a touch of distracted). The browser, cookies, and scroll position are preserved — only the motion/typing/reading profile changes.
- `human_set_speed`: Changes a session's humanization pace at runtime. "human" = full realistic motion (best for recordings); "fast" = humanized but quicker; "instant" = no humanized motion (straight Playwright). Note: this changes how long each action takes to execute, not the wait between actions. Cannot change while recording.
- `human_set_viewport`: Resizes a session's browser viewport at runtime. Use for a bigger/crisper recording or to test responsive layouts. The default size for new sessions is set by HUMANJS_VIEWPORT (default 1440×900).
- `human_emulate_media`: Emulates CSS media features for a session so you can verify the accessibility and theming paths a real user would get. `reducedMotion: 'reduce'` is the important one: it is the only way to check that a site's prefers-reduced-motion path actually works, and it is normally impossible to test without changing OS settings. Settings persist across navigations until changed; pass 'system' to stop emulating a feature.
- `human_browser_info`: Reports how the browser is obtained (ephemeral fresh profile, persistent profile, or attached over CDP), the channel, and whether logins persist. Use it to explain to the user why they are or are not signed in, and how to change it.
- `human_enable_persistence`: Switches HumanJS to a persistent browser profile so logins/cookies survive across runs. Takes effect on the next browser start; pass restartNow:true to apply immediately (restarting discards the current page — re-navigate after). For a permanent default, set HUMANJS_PERSIST=true in the MCP config instead. Note: this does NOT use your real Chrome profile (that stays an env-only, opt-in setting).
- `human_restart_browser`: Closes the browser and all sessions; the next action launches a fresh one in the current mode. Use to apply a persistence change, or to recover a wedged browser. Discards open pages/tabs — re-navigate afterward. (Does not affect a CDP-attached browser beyond disconnecting.)

## FAQ

### How do I add HumanJS to Claude Code?

Register the MCP server with a single command, or use the Cursor deeplink. It works with any MCP client, including Claude Desktop, Cursor, Codex, and Cline.

### Can HumanJS record a browser session as a video or GIF?

Yes. Wrap your actions in human.record() and export the recording to mp4, GIF, a JSON timeline, a runnable HumanJS script, or a Playwright test spec.

### Is HumanJS a stealth tool that bypasses bot detection?

No. It does not ship captcha solvers, fingerprint masking, or proxy rotation, and sophisticated anti-bot systems will still detect it.

### Does HumanJS support different interaction personalities?

Yes, it offers careful, fast, distracted, and precise personalities, which you can extend or blend.

### Can HumanJS runs be deterministic for tests?

Yes. Passing a seed makes runs deterministic, and speed: 'instant' keeps CI fast while full humanization runs locally.
