AginxBrowser
AginxBrowser
面向 AI 智能体的浏览器。查看实时网页,并与之交互。
一款从第一行代码起就为智能体而生的浏览器——不是把人类浏览器硬塞进自动化。看世界、读世界、搜世界、操作世界:一个内置 V8 的 Rust 二进制文件,无需 Chromium。
人类有 Chrome,智能体有 AginxBrowser。
一个二进制,零依赖,即时服务。HTTP API + 原生 MCP——智能体即插即用。
为什么智能体需要自己的浏览器
现有的“浏览器自动化”是为人类或一次性抓取而构建的,不是为智能体:
AginxBrowser | Puppeteer/Playwright | Firecrawl | Browser-use | |
设计面向 | 智能体优先 | 人类调试 | 抓取服务 | LLM 封装 |
依赖 | 单一二进制,无需 Chromium | Chromium ~500MB | Docker ~1GB | Chromium |
视觉(截图) | ✅ 内置 diting 渲染引擎 | 需要 Chromium | ❌ | 需要 Chromium |
读取 | markdown + js_extract | DIY | markdown | DIY |
搜索 | ✅ 5 引擎元搜索 | ❌ | ❌ | ❌ |
操作 | 索引会话交互 | DevTools API | ❌ | LLM 驱动 |
协议 | HTTP + 原生 MCP | Node API | HTTP | Python |
TLS 指纹 | ✅ Chrome/Firefox/Safari | 需要插件 | ❌ | ❌ |
验证码解决 | ✅ 自动 | DIY | ❌ | ❌ |
交互会话 | ✅ 持久 | ✅ | ❌ | ✅ |
智能体需要浏览器提供五样东西:看、读、搜、操作、部署。 一个二进制全部覆盖——对 systemd 友好,为 Claude/Cursor 提供 MCP 原生支持,零依赖。
核心优势:无需 Chromium。 AginxBrowser 内联了完整的浏览器引擎(V8 + Rust HTTP 栈 + 我们自己的 diting CSS/布局/绘制渲染引擎,以 Blitz/Stylo/Taffy 血统为参考实现)。没有 Puppeteer,没有 Chrome,没有 Docker。systemd 下的一个 Rust 二进制就是你的智能体浏览基础设施。
Related MCP server: Web Bridge
无状态渲染器做不到的三件事
大多数新型“智能体浏览器”是无状态、无指纹的一次性渲染器——对公开页面没问题,但面对 Cloudflare 或登录流程就寸步难行。AginxBrowser 反其道而行:
🔐 真实 TLS 指纹——隐身模式通过 BoringSSL 复制完整的 Chrome145 / Firefox133 / Safari / Edge TLS 握手(不只是 UA 字符串),可按请求切换;Cloudflare Turnstile 挑战会自动等待
cf_clearance。无指纹引擎吃 403——我们能通过。🤝 有状态交互会话——持久会话(8 分钟空闲保活),登录状态可注入和导出(
session_create(cookies=...)↔session_cookies),能撑过分页和多步流程。一次性引擎会丢弃状态。🔌 MCP 原生——14 个工具作为一等公民(不是 CDP 垫片)。Claude Code / Cursor / Claude Desktop 一行连接。HTTP + MCP 双协议。
参考点:Cloudflare 的 Kitesurf 明确不提供真实 TLS 指纹协商,也不提供持久认证会话——反爬和登录领域正是 AginxBrowser 的主场。
Apache-2.0 开源,单一二进制——今天即可自托管,无云锁定。
能力
分层渲染:静态页面走纯 HTTP(约 100ms);仅在需要 JS 渲染时启动 V8(约 1-2 秒)——约 80% 的页面快 10 倍
多引擎元搜索:通用网页(百度 / 必应 / 搜狗 / 微信 / Google)、新闻(Bing News)、代码(Stack Overflow、GitHub)、包(npm、PyPI)、学术(arXiv)、AI 模型(Hugging Face)——并发查询、合并去重。操作者可以将私有 Meilisearch 索引接入同一个
/search。搜索 → 读取一步完成图片搜索:
categories=images命中百度/必应图片索引,返回直接二进制image_url链接(可直接下载为 jpg/png)以及source_url来源交互会话:持久浏览器会话,带索引交互(
state/click/input/scroll/eval)——智能体像人类一样浏览验证码自动解决:类型检测,可选 2captcha 集成——搜索不会卡在验证页
JS 数据提取:
js_extract从 SPA 中提取window.__INITIAL_STATE__和其他结构化数据截图渲染:
/screenshot端点(可选--features screenshot)用我们自己的 diting 渲染引擎绘制 JS 渲染后的 DOM——纯 CPU,无 Chromium——输出 PNG。为智能体提供视觉输入Cloudflare 自动等待:检测“Just a moment...”挑战页并等待
cf_clearanceTLS 指纹伪装:隐身模式模拟 Chrome145/Firefox133/Safari/Edge,可按请求切换
MCP 服务器:
--mcp模式暴露 14 个工具(fetch/eval/click/search/download + 9 个会话工具)——Claude Code / Claude Desktop / Cursor 直接调用Firecrawl 兼容:
/v1/scrape端点——现有 Firecrawl 客户端只需更改 base URL 即可迁移DNS 重绑定防护:内置 SSRF 防护 + 解析后 IP 验证
用途
不是演示——是智能体浏览器今天正在做的实际工作:
攻克管理控制台——AWS / App Store Connect / Google Play,每个任务几十层菜单。让智能体点击;只在需要授权时才回来。
登录后的批量操作——填购物车、翻订单历史、检查仅登录后渲染的页面。注入 cookie、操作、导出复用。
穿越反爬墙——Cloudflare 防护、Turnstile 挑战、TLS 指纹检查。隐身模式硬闯,而不是在 403 前退缩。
中文互联网——百度 / 搜狗 / 微信 5 引擎元搜索,正确渲染中文页面。不只面向英文网络。
现场脚本——智能体读页面、写 JS、执行:高亮对比表、重排内容、按隐藏参数筛选产品。加强版 GreaseMonkey。
多模态视觉——截图作为视觉输入用于“看-判断”流程:选座位、识别布局、验证渲染。
快速开始
先试试托管实例:https://browser.aginx.net/
一键完整安装(SKILL.md 触发面 + MCP 工具 + 验证):
# Download -> inspect the contents -> run only after review (never blind-run network scripts)
curl -fsSL https://raw.githubusercontent.com/yinnho/aginxbrowser/main/skill.sh -o skill.sh
less skill.sh
bash skill.sh仅注册 MCP:
claude mcp add aginxbrowser --transport http https://browser.aginx.net/mcp通过 skills.sh 安装技能触发面:
npx skills add yinnho/aginxbrowser自托管:
# Prebuilt binary (one-line installer: platform detect + sha256 + self-check)
curl -fsSL https://raw.githubusercontent.com/yinnho/aginxbrowser/main/install.sh -o install.sh
less install.sh && bash install.sh
aginxbrowser doctor # features + fonts + egress self-check
# Or build from source (--features stealth,screenshot or you lose both)
cargo build --release --features stealth,screenshot
# Start the service
./target/release/aginxbrowser
# → Listening on 0.0.0.0:8089
# Verify
curl http://127.0.0.1:8089/health
# → {"status":"ok","engine":"diting"}
# Fetch a page
curl -sS -X POST http://127.0.0.1:8089/fetch \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'
# Search
curl -sS -X POST http://127.0.0.1:8089/search \
-H "Content-Type: application/json" \
-d '{"q":"macbook price","max_results":5}'
# Create an interactive session
curl -sS -X POST http://127.0.0.1:8089/session/create \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'
# → {"session_id":"s_1","url":"https://example.com/"}
# MCP mode (for AI agents)
./target/release/aginxbrowser --mcp项目结构
aginxbrowser/
├── Cargo.toml
├── build.rs # V8 snapshot generation
├── js/
│ └── bootstrap.js # V8 bootstrap script
├── README.md
├── docs/
│ └── API.md # Full API reference (HTTP + MCP)
└── src/
├── main.rs # HTTP service entry & routing
├── server.rs # Business layer (fetch/click/eval/search)
├── session.rs # Interactive browser sessions
├── captcha.rs # CAPTCHA detection & auto-solve
├── render.rs # Tiered rendering (HTTP direct → diting browser engine)
├── mcp.rs # MCP server (14 tools)
├── firecrawl_compat.rs # Firecrawl-compatible /v1/scrape endpoint
├── browser.rs # Top-level API: Browser, BrowserBuilder
├── page.rs # Top-level API: Page, Element
├── config.rs # BrowserConfig
├── cookie.rs # CookieStore
├── error.rs # Error types
├── search/ # Native search engines
│ ├── mod.rs # SearchEngine trait, Registry, merge/dedupe, progressive backoff
│ ├── baidu.rs # Baidu (JSON API, wreq stealth)
│ ├── bing.rs # Bing (HTML parsing, plain reqwest)
│ ├── sogou.rs # Sogou web (HTML parsing, plain reqwest)
│ ├── sogou_wechat.rs # Sogou WeChat (HTML parsing + /link resolution)
│ ├── google.rs # Google (HTML parsing, wreq stealth + proxy)
│ ├── stackexchange.rs # Stack Overflow (SE API v2.3, code category)
│ ├── github_repos.rs # GitHub repos (api.github.com, code category)
│ ├── arxiv.rs # arXiv (Atom API, academic category)
│ ├── bing_news.rs # Bing News RSS (news category; proxy-first)
│ ├── huggingface.rs # HF Hub models/datasets/spaces (ai category)
│ ├── npm.rs # npm packages (npms.io API, packages category)
│ ├── pypi.rs # PyPI name resolution (JSON API, packages)
│ └── meilisearch.rs # Private-index adapter (env-configured)
│
├── diting_dom/ # HTML parsing, DOM tree, CSS selectors
├── diting_net/ # HTTP client, cookies, encoding, proxies
├── diting_js/ # V8 runtime, JS ops, module loading
└── diting_browser/ # Page navigation, lifecycle, browser context构建
# Standard build (no stealth; TLS fingerprint features inactive)
cargo build --release
# With stealth (requires go + cmake + C++ toolchain; enables TLS fingerprint spoofing)
cargo build --release --features stealth
# With screenshot rendering (enables /screenshot; adds the rendering stack, +30-40MB)
cargo build --release --features screenshot
# Full featured (recommended for production)
cargo build --release --features stealth,screenshot要求:Rust 1.78+;V8 静态库在首次构建时自动下载。隐身功能额外需要 go、cmake 和 C++ 编译器。截图功能附带内置 CJK 字体子集(GB2312 + 常用符号)——无需系统字体即可正确渲染中文。
运行时环境变量
变量 | 默认值 | 说明 |
|
| 监听地址 |
| enabled |
|
| Linux Chrome145 | 伪装的 User-Agent |
|
| Accept-Language 请求头 |
| none | 可选的回退代理。数据源被屏蔽的引擎(Google、Bing News、Hugging Face)会先直连,仅当直连失败时才回退到该代理——海外部署完全无需代理;请求级 |
|
|
|
| none | 2captcha API 密钥;启用 CAPTCHA 自动求解 |
|
| CAPTCHA 求解服务提供商 |
| none | Meilisearch 基础 URL;设置后启用私有索引引擎 |
| none | 要查询的 Meilisearch 索引 uid |
| none | 用于 Meilisearch 实例的可选 Bearer 密钥 |
API 文档
完整 API 参考 → docs/API.md
安全审计说明 → docs/skills-sh-audit.md — 为什么 skills.sh 会显示“Critical Risk”,以及每条警告对应哪个真实产品功能
涵盖:
所有 HTTP 端点(
/fetch、/click、/evval、/seh... 保持原文:/fetch、/click、/eval、/search、/v1/scrape`、8 个会话端点)全部 14 个 MCP 服务器工具及其参数
Claude Code / Claude Desktop / Cursor 客户端配置
环境变量、错误码、各站点的抓取示例
接入其他系统
AginxBrowser 是纯粹的旁挂式基础设施——与真实浏览器一样,它以独立服务的形式运行,任何东西都能调用,无需嵌入宿主代码,也不会污染宿主配置。每台机器部署一个实例(由 systemd 托管),所有需要“渲染 + 抓取”能力的应用共享该实例。
集成方式:读取环境变量 AGINXBROWSER_URL=http://127.0.0.1:8089。未设置 → 行为不变;设置后 → 受风控的站点会自动经由 AginxBrowser 进行渲染,失败时优雅回退。
已知限制
截图功能为可选:
/screenshot需要执行car... 保持原文:/screenshot需要cargo build --release --features screenshot(引入渲染栈,+30-40MB)。默认渲染引擎为 diting(我们自研的 CSS+布局+绘制栈);传入engine: "blitz"可重新选用 Blitz 参考管线。两者在复杂站点的 CSS 渲染上都只是近似(无法像 Chromium 那样像素级精确)支持元素坐标(块级):带
selector的/screenshot会返回元素的页面坐标(selector_rects,CSS px);仅传入selector则会直接裁剪到该元素。纯内联元素(<<a>text</a>)没有独立的盒子——请选择块级祖先元素JS 交互大体可用;强指纹页面仍可能失败:React/Vue 的事件委托可以正常工作(
src/href等 URL 反射属性会解析为绝对 URL,因此 Next.js/webpack 能够正常水合,点击也能触发事件处理器)。在 stealth 指纹覆盖完成之前,探测navigator.plugins、WebGL canvas 等的强指纹认证页面(WorkOS/Cloudflare)仍可能失败代理支持:通过
AGINXBROWSER_PROXY支持 HTTP/HTTPS/SOCKS5风控严格的站点:不支持 Baidu Wenku;Zhihu 文章需要有效的
__zse_ck
许可证
与 OpenCarrier 主项目保持一致。Apache-2.0。
Available Tools
40 toolsaccount_deleteAInspect
Delete a named login identity: stored record AND live jar. Cookie values are credentials — delete means gone. Sessions currently running as the account keep their in-process jar handle, but nothing writes back. Returns {deleted: name}, or an error naming the account if it does not exist.
Inputs: name (required).
account_listARead-onlyInspect
List named login identities (the multi-account layer) with metadata only: name, cookie domains, cookie count, updated_at, the last account_verify verdict, and the identity's persona User-Agent (each account is one stable device: its own UA and hardware fingerprint, drawn once and reused). Cookie values are credentials and never leave the server. Use to see which identities exist before session_create {account} picks one.
Inputs: no named parameters.
account_loginAInspect
Open a site's login page AS a named account and close the login loop. Creates the session as the account (private jar, device persona), navigates to url, and reports which generic login gates the page shows — needs: password | sms | qr | slider (QR scan like xiaohongshu, SMS code, password form, slider/captcha) — plus a session_verdict classification and, when a human step is needed, the session_id and a /live handoff so a person can finish it in the live view (the engine detects and describes; it never fills credentials or solves challenges). With predicate and no human gates detected, waits for the automatic bounce, then teaches + stamps the account's verify spec — later account_verify calls re-check it bare. Cookies write back after every action, so a login finished in /live is already persisted. status is "logged_in" (verify stamped), "waiting" (drive session_wait/session_input on session_id, or re-call account_login after the human finishes — the account's shared jar already holds it), or "opened" (no predicate given).
Inputs: url (required), name (required), predicate, use_proxy, +1 more.
account_verifyAInspect
Check whether a named account is still logged in. Teach-once: the first call passes url + predicate (a JS expression truthy on a logged-in page, e.g. !!document.querySelector('.user-nick')); the spec is remembered and later calls can be bare. Runs in a scratch session AS the account (private jar), so the probe doubles as a cookie refresh. Returns {name, logged_in, url, checked_at}.
Inputs: name (required), url, predicate.
cacheAInspect
Query the LOCAL CACHE of every page this server has fetched and every search it has run. Check here BEFORE re-fetching or re-searching — a hit is instant and free while a fresh fetch costs 5-60s. Use query for full-text search (works for Chinese substrings and English words), get to pull a page's full cached content, stats for counts, clear to delete rows.
Inputs: all, get, url, kind, +5 more.
clickAInspect
Click an element on a one-off page: loads url in a fresh browser context (stateless — no cookies unless passed, no shared state with other calls), waits wait_secs after load before clicking, then fires a DOM click on the first CSS-selector match. The click may trigger navigation (link, form submit) — the response url and text_after are read after that navigation lands. Returns clicked:false when the selector matches nothing. For multi-step interaction on a shared page use session_click instead.
Inputs: url (required), selector (required), wait_secs.
downloadAInspect
Download a file over HTTP(S) with streaming to disk (no memory buffering), SHA-256 integrity hash, and optional resume of interrupted transfers. Filename resolution: explicit param → Content-Disposition → URL tail. Use for binaries, archives, datasets, documents - anything where the agent wants the FILE saved, not its text content read.
Inputs: url (required), resume, cookies, filename, +1 more.
evalAInspect
Execute JavaScript on a one-off page: loads url in a fresh browser context, optionally waits wait_secs for the page to settle, evaluates script (async/Promise supported) and returns {url, result}. Script-driven navigation (location.href, form submit) is drained and reflected in the returned url. Stateless — no cookies or page state shared with other calls; when the script needs prior page state or a login, use session_eval.
Inputs: url (required), script (required), wait_secs.
fetchARead-onlyInspect
Fetch a webpage and return clean markdown/html/text. Use whenever the agent needs to READ any web page - blogs, docs, articles, JS-rendered SPAs, Cloudflare-protected sites. Static pages are served over plain HTTP (~100ms tier:"http"); pages that need JS get the full browser (tier:"browser"). render_tier selects auto (default) / http (pure HTTP, refuses the upgrade) / browser (always the JS browser).
Inputs: url (required), format, sanitize, selector, +8 more.
flow_runAInspect
Run a flow — a recorded, editable JSON browser-session script — deterministically, with zero model tokens. Steps are {op, args, expect?, save?}: ops cover navigate/click/click_xy/input/scroll/eval/wait/screenshot/state/cookies; {{var}} placeholders in args are filled from vars; expect asserts (url_contains | selector | text_contains | eval_truthy) abort with evidence on failure; save collects a step's output into the receipt. Source the flow inline via "flow", or by "name" from the server's workflow//flow.json (unknown name → error lists installed workflows). Pass session_id to reuse a live session (e.g. from import_curl) so login state and flows compose. The receipt carries status ok/failed, saved outputs, the session_id (kept alive), and on failure the failing step, reason and a diagnostic screenshot — fix the flow or take the session over from there.
Inputs: flow, name, vars, max_steps, +1 more.
import_curlAInspect
Import login state from a real browser in one paste. The human logs into a site in their own Chrome (solving the CAPTCHA/SMS once), opens DevTools → Network, right-clicks any authenticated request → "Copy as cURL", and passes the command here. Returns a live session_id already carrying that site's cookies and sitting on the copied request's URL — the agent continues from where the human left off, no password or second login needed. Works with bash, PowerShell and cmd copy flavors.
Inputs: curl (required), account, use_proxy.
render_markdownAInspect
Render a markdown document into a deterministic, self-contained HTML artifact - the document layer, so the agent never writes HTML by hand. Prose rides a plain offline shell (no fonts, no scripts); archify fenced code blocks carry typed zero-coordinate diagram JSON (sequence, workflow, architecture, dataflow, lifecycle families) and render to inline SVG via the layout engine. Same input, same bytes: the receipt carries the sha256 so determinism is verifiable. theme picks light (default) or dark; preset picks the palette family — classic (default), signal-flow, blueprint, editorial — orthogonal to theme; colors bake at generation time (presentation attributes, not CSS variables), and the receipt records both preset and theme. quality picks the composition audit profile — standard (default) or showcase, the delivery gate: the receipt's diagrams[].composition grades route crossings, ambiguous corridors, label clearance (2px standard / 4px showcase), route rhythm, and node text projected to the 930px reader width; the audit never changes the artifact bytes. Mermaid sources are the agent's job to translate, not the engine's: flowchart/graph → workflow (lanes + columns), sequenceDiagram → sequence, stateDiagram-v2 → lifecycle (bands), erDiagram/class → architecture (grid + boundaries) — read the topology and emit the matching zero-coordinate archify JSON; the engine accepts only archify JSON. A broken diagram degrades to a visible code block and lands in receipt.diagnostics; an authored route preset that cannot be honored is self-repaired to a verified semantic substitute and disclosed in receipt diagrams[].repairs - the document still renders. A fence may also carry views: [{id,label,nodes,note?}] (node ids of the active family), emitted as guided-view tabs above the diagram plus an inlined viewer script - clicking a tab lights the member nodes and the routes between them (subgraph), clicking a node lights it with its direct neighbors (ego graph), everything else dims; a view's optional note shows as a caption while it is active (the story layer). window.agxViewer in a session drives and reads the same state programmatically: {focus,view,state} as before, plus route(i,from,to) which returns and lights the shortest authored directed path between two nodes (null when unreachable, state untouched), and reach(i,id,down|up) which returns and lights the authored downstream/upstream closure ({nodes,links}); both dim the rest of the diagram. diagrams[].views in the receipt lists the tabs. motion: true bakes an entrance choreography into the artifact: pure-declarative CSS animation with zero scripts - headings split into per-glyph (CJK) / per-word (latin) spans that rise in with expo easing, prose blocks stagger up an nth-child delay ladder, diagram figures grow in with a back ease (GSAP's easing math as public cubic-bezier equivalents, nothing embedded); the diagrams themselves play a flow story on the same clock - nodes land beat by beat, solid edges draw in (dash-offset), dashed returns fade, sequence messages arrive as sent - with a timed caption strip under each figure as the subtitles, which becomes a static transcript under prefers-reduced-motion; the file itself animates in any browser and the receipt records motion plus diagrams[].story (beat times and captions - the hook for muxing voice later). With session_id the artifact is also loaded into that session (local, free) and the reply carries viewport acceptance: scroll extents measured in the live session and graded fits/tall/wide/oversized, telling the agent how to read the page back. Diagram vocabulary adapted from archify (MIT).
Inputs: markdown (required), theme, motion, preset, +2 more.
render_pdfAInspect
Cut a rendered page into pages and package as PDF, PNGs, PPTX or DOCX. Print mode (no selector) paginates the document into fixed-height pages (default 794x1123, A4 @96dpi), breaking at top-level block boundaries — no half-cut text where a break can land on a block edge. Slides mode (selector set) makes one page per match, sized to that element — generate an HTML deck with one .slide per page and each becomes a deck page. format "pdf" (default) returns base64 image-based PDF; "png" returns one base64 PNG per page in pages_base64; "pptx" returns a base64 PPTX (one slide per page, deck-sized to the largest page); "docx" returns a base64 DOCX (one page-sized section per page, each section keeps its own height). Returns page count and packaging.
Inputs: url (required), width, format, height, +5 more.
render_videoAInspect
Render a page's animation timelines to an MP4 video. The page's scripts must expose window.__timelines — objects with duration() and pause(t) (a paused gsap.timeline registered there works as-is). Each frame seeks every timeline to t=i/fps and paints the viewport, so the output is deterministic — no wall clock in the pixel values. Audio: narration[] places TTS/voice clips at start times (mixed into one AAC track), audio adds looped background music, and subtitles_srt muxes an SRT as a soft mov_text track and (by default, burn_subtitles: false to opt out) burns the same cues into the frame pixels — QuickTime, WeChat and most social embeds ignore the soft track. Requires ffmpeg on the server. Returns base64 MP4 (H.264, yuv420p) plus frame count and durations.
Inputs: url (required), fps, audio, width, +10 more.
searchARead-onlyInspect
Search the web across Baidu/Bing/Sogou/WeChat/Google (aggregated + deduped) and optionally fetch the top results' full content. Use when the agent needs to FIND information online - replaces a search API. Supports image search returning direct image URLs. Optional engines: ["baidu"]-style filter by engine name (invalid names error with the valid list; /doctor lists them with live health). Optional time_range day/week/month/year for news freshness (engines without dated results ignore it). Response carries engine_errors explaining any engine that contributed nothing (CAPTCHA suspension, transient failure).
Inputs: q (required), engines, fetch_top, categories, +3 more.
session_challengesARead-onlyInspect
One-call risk-control report: did this session hit an anti-bot wall? Taobao/tmall's x5 risk control answers 200 like a normal response — either a redirect onto a punish page (tmd/punish, punish.taobao.com) or an MTop API body carrying FAIL_SYS_USER_VALIDATE / RGV587 / x5secdata. Returns {total, events:[{url,method,status,kind,via}]} where via says whether the wall was navigated into ("url") or swallowed by an API response ("body"). When there are hits, the response also carries the account name (which identity got walled) and a handoff instruction: the engine detects and surfaces but does not auto-bypass — a human opens the live view (/live?session= on the engine's HTTP port), solves the challenge in this session, and the retry rides the cookie that solving sets. Detection only; no automated solving or bypass.
Inputs: session_id (required).
session_clickAInspect
Click an interactive element by its index (from session_state output) inside a live browser session: scrolls it into view and fires a DOM click on the session's current page. Before clicking it re-verifies the element in the same frame — if the page changed since session_state (element detached, disabled, hidden, or covered by an overlay), it returns clicked:false with a reason ("detached"/"disabled"/"not_visible"/"covered_by") and, when covered, a covered_by description of the element that would eat the click — never a silent no-op. A submit click may navigate the session — the returned url/text_after reflect the page after the action, and session state (cookies, localStorage, globals) persists for follow-up calls. Indexes come from the most recent session_state; re-list after navigation.
Inputs: index (required), session_id (required).
session_click_xyAInspect
Click at viewport coordinates (CSS pixels) via real mouse events — pointerdown/mousedown, pointerup/mouseup, then click on whatever element is hit there. For canvas/map surfaces with no DOM element to index. click_count 2 adds dblclick.
Inputs: x (required), y (required), session_id (required), button, +1 more.
session_cloneAInspect
Derive a new browser session from a live one, carrying the full login state: cookies, localStorage/sessionStorage, viewport pin, dialog policy, proxy and keepalive flags. The source session stays untouched. Use to snapshot a logged-in state before risky actions, or to run the same login in parallel tabs. Returns {session_id (new), cloned_from, url, viewport}.
Inputs: session_id (required).
session_closeAInspect
Close a browser session and free its resources. For a persistent session this also drops the on-disk login snapshot - idle expiry keeps it, an explicit close does not.
Inputs: session_id (required).
session_consoleARead-onlyInspect
Read the session's recent page console output (log/info/warn/error) as {url, total, matched, messages:[{ts_ms, level, text, url}]}, newest last. Ring buffer of 500 entries; captures output from page scripts, clicks, evals and navigation alike. Optional filters: level (exact, e.g. "error"), since_ts (epoch ms), url_contains (page URL substring), limit (most recent N matches). The fastest way to see WHY a page misbehaves: click the button, call this, read the error.
Inputs: session_id (required), level, limit, since_ts, +1 more.
session_cookiesARead-onlyInspect
Export the session's current cookies as ["name=value", ...] for the page's URL. Use to persist a logged-in session and replay it later via session_create with cookies. Round-trips with session_create's cookies field.
Inputs: session_id (required).
session_createAInspect
Create a persistent interactive browser session for multi-step interaction - clicking, typing, scrolling, reading state across page transitions. Use when the agent must INTERACT with a page (login flows, forms, pagination, click-through) rather than read it once. Returns session_id; persists 8 min idle. With persistent:true the login state survives idle eviction and server restarts - the same session_id revives logged-in.
Inputs: url, width, height, mobile, +7 more.
session_dialogAInspect
Inspect or flip the session's dialog policy for window.alert/confirm/prompt. Dialogs never block the page: each is auto-answered (default dismiss) and logged into session_console at level "dialog". action "list" reports {policy, prompt_text, dialogs}; "accept" makes subsequent confirm() true and prompt() return prompt_text (or the call's default argument); "dismiss" restores the default.
Inputs: action (required), session_id (required), prompt_text.
session_dragAInspect
Drag the mouse from one viewport position to another: press at from, steps mousemove events, release at to. The trajectory is humanized by default (eased velocity, wobble, jittered timing, overshoot) — the shapes anti-bot checks score for; pass humanize:false for exact linear interpolation. Moves AMarker-style drag targets, canvas selections and captcha sliders that only track while the pointer travels.
Inputs: to (required), from (required), session_id (required), steps, +2 more.
session_evalAInspect
Execute arbitrary JavaScript in a live browser session and return the result. Runs in the session's current page, so DOM mutations, globals and storage persist across calls — unlike the stateless eval tool, which loads its own throwaway page each call. Script-driven navigation moves the session's URL. JS exceptions are reported with name, line/column and stack.
Inputs: script (required), session_id (required), timeout_ms.
session_exportARead-onlyInspect
Export a browser session's recorded action log. Format "bash" (default) returns a runnable curl script that replays every recorded action (navigate/click/input/scroll/eval) against a fresh session on this server — hand it to a shell or cron, zero model tokens. Format "jsonl" returns the raw action log, one JSON object per line. Format "json" returns a flow.json document — the same recording as editable ops ({op, args}) with cookies/storage stripped — that flow_run replays server-side.
Inputs: session_id (required), format.
session_inputAInspect
Type text into an input/textarea element by its index (from session_state output), focusing it and dispatching input/change events. events:"full" is the complete human typing gesture: per-character keydown/keypress/input/keyup cycles, trailing change, then blur — the tail blur commits on forms that save in onBlur (React capture listeners, #100). A disabled, readonly, or detached field answers filled:false with a reason instead of a silent write. Hidden inputs are legitimate targets and are filled normally.
Inputs: text (required), index (required), session_id (required), events.
session_listARead-onlyInspect
List live browser sessions with idle age and the time left before auto-eviction. Use to discover a session to reuse instead of creating a new one; sessions expire after 8 min idle.
Inputs: no named parameters.
session_networkARead-onlyInspect
Read the session's network request log. filter="media" extracts playback/stream URLs (m3u8/HLS, mp4, dash, flv...) actually requested by the page's player at runtime - the reliable way to get a real video link, since links embedded in page HTML are often decoys. Media elements and player iframes the engine never fetches (video/audio/source/iframe src) are merged in as candidates: via="network" entries are confirmed requests, via="dom" entries are candidates carrying their tag (iframes = kind "iframe", navigate into them to sniff). Default returns every request as compact rows (method/url/status/type/size). Navigate to the video page first, let it load, then call this.
Inputs: session_id (required), filter, url_contains, body_max_chars, +1 more.
session_preloadAInspect
Replace the session's document-start preload group (empty array clears). Sources run before each new document's own scripts — including inline tags — which is the only hook that beats pages whose signing layer captures window.fetch/XHR natives at parse time (xhs's inline jsvmp). Set before the first navigate; applies to every navigation from then on.
Inputs: session_id (required), scripts.
session_screenshotAInspect
Screenshot the session's CURRENT DOM state (mutations from clicks/evals included) as a base64 PNG via the built-in renderer. Width/height default to the session's viewport, so session_viewport + session_screenshot shows the responsive layout. Returns {url, width, height, image_base64, format}.
Inputs: session_id (required), width, height, selector, +2 more.
session_scrollAInspect
Scroll the page up or down by a number of viewport-heights.
Inputs: session_id (required), amount, direction.
session_set_filesAInspect
Select files on a file input programmatically (Playwright setInputFiles semantics): builds File objects from base64 content, assigns them to input.files, then dispatches input+change so framework onChange handlers fire. Selector-addressed because file inputs are often hidden and absent from the session_state index.
Inputs: files (required), selector (required), session_id (required).
session_stateARead-onlyInspect
Get the current page state as an indexed list of interactive elements. Returns compact text with [N] indexes for use with click/input tools.
Inputs: session_id (required).
session_storageARead-onlyInspect
Snapshot the session's localStorage/sessionStorage for the current origin: {url, local_storage, session_storage}. Feed it back via session_create's storage field to restore a logged-in state in a new session — the half of login state that cookies can't carry (many sites keep the session token in localStorage). Call before the session idles out.
Inputs: session_id (required).
session_verdictARead-onlyInspect
One call answers "where did this session land": verdict is one of challenge (risk control engaged — punish page or a 200-status API body that swallowed the wall; the response carries a handoff instruction for a human to solve it in the live view), captcha (explicit CAPTCHA interstitial), login (bounced to a login form — auth expired), empty, landed (normal 2xx content page), or unknown (couldn't classify — read facts; a non-2xx main document lands here with facts.doc_status carrying the number, so a zhihu-style burst 403 is branchable). The facts sheet also carries challenge_events, requests, console_errors and the fired signals. Pure code over signals the engine already holds (current URL, risk-control rows, main document status/size, console errors) — no screenshots, no page evals, single-digit milliseconds. Verdict observes, it never bypasses.
Inputs: session_id (required).
session_viewportAInspect
Set the session's viewport (device emulation): scripts see innerWidth/innerHeight move, media queries like (max-width: 600px) re-evaluate, element rects re-anchor, and mobile=true flips pointer/hover matchMedia answers to coarse/none. Omitted width/height keeps the current value.
Inputs: session_id (required), width, height, mobile.
session_waitARead-onlyInspect
Wait until a CSS selector matches or a JS predicate turns truthy, with a timeout. The page's event loop keeps running while waiting (fetches, timers, promise chains progress), so this replaces blind sleeps for async content: navigate, session_wait for '.price-card', then click/read. Returns {matched, elapsed_ms, detail:{tag,text} or the predicate value}; errors with timeout ... naming the selector/predicate on expiry. Exactly one of selector/predicate.
Inputs: session_id (required), selector, predicate, timeout_ms.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 40 tools
Tool families are cleanly separated: stateless fetch/eval/click are explicitly distinguished from their session_* counterparts, and account_*/render_*/session_* names signal intent. The main fuzzy boundaries are session_challenges vs session_verdict (both report anti-bot/risk status) and the three render_* tools, though descriptions usually resolve them.
Most tools follow predictable families—account_<verb>, session_<operation>, render_<format>—and bare stateless verbs (fetch, search, eval, click) are easy to read. Deviations such as flow_run instead of run_flow and noun-style read tools like session_state/session_network/session_cookies keep it from being perfectly uniform.
40 tools is a heavy surface, especially with 26 session_* variants; even though each is a real browser action, the set will tax an agent's selection and context budget. The server's broad scope explains the count, but it still exceeds what most MCP clients handle gracefully.
The surface covers the full browser workflow: read/search/download, session lifecycle and input, login-state persistence, risk-control verdicts, flow replay, and render/export targets. Minor gaps such as no explicit multi-tab/window management or standalone proxy/user-agent configuration are workaroundable.
Maintenance
Related MCP Connectors
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Cloud browser, web extraction, screenshots, and remote CDP tools for AI agents.
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Web infrastructure for AI agents: scrape, crawl and search the web, run browsers and agents.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceA Playwright-based MCP server that exposes a live browser as a traceable, inspectable, debuggable and controllable execution environment for AI agents.5,213 npm57-
- AlicenseAqualityCmaintenanceBrowser automation MCP server that uses a real browser to give agents eyes and hands—open pages, click, fill, screenshot, and run scripts via accessibility-tree snapshots.226 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables an AI agent to observe, plan, and act inside a real browser session by exposing navigation, snapshot, click, type, and screenshot MCP tools over local JSON-RPC and SSE. It runs a Playwright-backed browser in-process and provides stable element references for reliable actions.MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to run Playwright-compatible browser automation with persistent profiles, proxies, Chrome extensions, and humanized mouse, keyboard, and scroll interactions over stdio or Streamable HTTP. Supports web research, daily automation, testing workflows, and optional session-scoped CDP access.280 npmMIT