Sleeper
Sleeper's MCP server lets agents control a connected browser session to navigate, inspect, interact with, wait on, extract from, and automate web pages.
Discover connected browsers and tabs with
sleeper_sessions,sleeper_tabs,sleeper_state, andsleeper_frames.Navigate with
sleeper_goto,sleeper_back, andsleeper_newtab.Inspect pages/elements with
sleeper_snapshot,sleeper_get,sleeper_find,sleeper_find_text,sleeper_read,sleeper_read_all, andsleeper_extract.Interact via click, click-all, click-text, hover, focus, type, keys, press, submit, select, check/uncheck, double-click, and drag tools.
Work with forms using
sleeper_formsandsleeper_fill_form.Wait on selectors, text, URLs, dialogs, XHR, downloads, or structured/JS conditions.
Scroll using
sleeper_scrollandsleeper_scroll_until.Inspect network/media/console activity and call page APIs with captured auth via
sleeper_network,sleeper_media,sleeper_console, andsleeper_api.Capture viewport screenshots with
sleeper_shot/sleeper_screenshot.Upload base64 file contents (max 1 MiB JSON request) with
sleeper_upload.Run ordered batches up to 50 actions with
sleeper_batch.Execute arbitrary JS in Chromium with
sleeper_exec; signed Firefox builds do not support it.Target a specific browser profile/tab via
profileandtabparameters.
Enables running Sleeper on Android to control Firefox for Android through a private Tailscale Serve connection to a desktop daemon, supporting mobile browser automation.
Controls an existing Firefox session (desktop or Android) through the Sleeper extension, enabling navigation, page reading, form filling, screenshots, and structured data extraction without copying session credentials.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Sleeper Open my Amazon orders page and screenshot the latest delivery status"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Sleeper
English · 简体中文 · 日本語 · Português · Español · Deutsch

Let your agent control the browser you already use, whether it’s on your desktop or Android phone. Sleeper connects Firefox or Chromium through MCP or CLI to navigate websites, read pages, fill forms, take screenshots, and extract structured data without copying session credentials into agent configuration.
Features · Install · Commands · Agent setup · Privacy · Security · Benchmarks · Contribute
Features
📱 Firefox for Android (beta): Run Sleeper on Android through a private Tailscale Serve connection to your desktop daemon. No Caddy, router port, or public listener is required.
🖥️ Firefox + Chromium desktop: Control pages in an existing browser session through the extension. Linux and macOS are supported; Windows is best-effort.
🗂️ Profiles and tabs: Each browser installation has its own persistent ID. Agents discover connected browsers and target the intended tab.
🎯 Element targeting: Find controls by CSS selector, accessible role and name, or a reference returned by
snapshot.📝 Page interaction: Fill inputs, press keys, click controls, and wait for selectors or text before the next action.
📋 Structured extraction: Read one element, collect matching elements, or extract a JSON map. Save repeatable work as recipes and schemas.
📸 Screenshots: Capture the viewport or full page, with optional annotations. PNG output has a size limit; capture options explain it.
🌐 Network and APIs: Inspect captured requests and call allowed HTTPS APIs with credentials kept in the browser and bound to their source host.
🔒 Secret masking: Structured results receive best-effort redaction before reaching the CLI or MCP client. Screenshots can still contain private information.
🔌 CLI and MCP: Run shell commands or call MCP tools through the local daemon.
📖 Included skill: Give agents instructions for session selection, action verification, and connection recovery.
Related MCP server: browser-control
Install
Install uv first, then run from a checkout on Linux or macOS (the supported desktop platforms):
./install.shWindows works on a best-effort basis and is not a launch-supported platform; run in PowerShell:
py scripts/install.pyChoose Everything or Customize to select MCP, native agent plugins, and standalone instructions. The installer starts the daemon, installs the CLI, registers Firefox's extension-scoped native host for automatic XPI pairing, keeps Chromium's extension in a permanent folder, and copies browser packages to Downloads.
Firefox for Android connects through Tailscale Serve (beta). Run sleeper mobile setup, then open the QR code in Firefox; see the Android setup guide. The daemon remains loopback-only.
Troubleshooting
Toolbar icon opens a thin full-width strip instead of the popup — fixed by using a fixed popup width; rebuild and reinstall the extension package (see docs/commands.md for daemon environment configuration).
"no browser connected" / popup shows "Daemon disconnected" — check curl http://127.0.0.1:8790/health (daemon must be running), then run sleeper sessions (your browser should appear under profiles). For Firefox, rerun ./install.sh update if the native host was not registered; the fields under Advanced connection are manual recovery only. Extension origins are pinned to the first browser add-on that pairs with the daemon; restrict them further with SLEEPER_ALLOW_ANY_EXTENSION=false and SLEEPER_ALLOWED_EXTENSION_IDS=<uuid>,... in the daemon's startup service (systemd user unit on Linux, LaunchAgent on macOS — see docs/commands.md).
Run sleeper --version for the installed CLI version. sleeper sessions reports daemon, protocol, and connected add-on versions; an incompatible or older add-on is marked in its browser record.
Codex and Claude Code
The main installer can register Sleeper's native plugin when you choose Everything or Customize. For manual setup, install the Sleeper runtime first, then run the commands for your agent from the repository root.
Codex
codex plugin marketplace add .
codex plugin add sleeper --marketplace sleeper-localClaude Code
claude plugin marketplace add . --scope user
claude plugin install sleeper@sleeper --scope user# Codex
codex plugin marketplace add https://github.com/shy-tangerine/Sleeper.git
codex plugin add sleeper --marketplace sleeper-local
# Claude Code
claude plugin marketplace add https://github.com/shy-tangerine/Sleeper.git --scope user
claude plugin install sleeper@sleeper --scope userRestart the agent after installation so it loads the bundled skill and MCP server. See agent setup for public-GitHub installation, verification, updates, and removal commands.
Browser | Finish installation |
Chromium | Open the extensions page, enable Developer mode, choose Load unpacked, and select the folder printed by the installer. |
Firefox | Install the signed |
Browser permission approval is required once. Installation, updates, and removal.
Prefer manual client setup? Use the verified Codex and Claude Code plugin commands.
curl -fsSL https://raw.githubusercontent.com/shy-tangerine/Sleeper/main/install.sh | bashInspect the open tabs and current page:
sleeper tabs
sleeper snapshot
sleeper type --role textbox --name Search 'your query' --clear
sleeper press EnterWhile an agent is working, Sleeper can show a small on-page activity message such as “Opening a page…”, “Clicked an element”, or “Timed out waiting for the page.” These messages use plain language rather than CLI/MCP command names. Typed values, uploaded file contents, and other sensitive action values are not shown. Visible activity can be turned off in the extension settings; the toolbar still exposes connection and access state.
The included agent skill covers session selection, action verification, and connection recovery. Agents can use MCP tools directly; the command guide covers tab targets, extraction, recipes, and API calls.
Waiting | Working |
Benchmarks
Five verified runs per interface, on one machine. Each sequence navigates, reads a heading, types, clicks, waits for text, and reads the result.
Tested on Linux with Helium 0.17.0.1 (Chromium 153.0.8010.36). Every interface used the same browser build and a fresh profile.
Percentages use the rounded medians below.
Interface | Median sequence | Median browser RSS | Task-text tokens | Protocol-text tokens |
Sleeper CLI | 934 ms | 1,139 MiB | 441 | 409 (HTTP JSON) |
Sleeper MCP | 281 ms | 1,127 MiB | 502 | 695 (JSON-RPC) |
OpenCLI | 4,011 ms | 1,218 MiB | 364 | 29,152 (HTTP JSON) |
Playwright MCP | 1,635 ms | 1,027 MiB | 536 | 734 (JSON-RPC) |
Direct CDP | 291 ms | 1,038 MiB | Not applicable | 956 (CDP) |
Task-text tokens estimate agent-facing input and output with o200k_base. Protocol tokens count internal HTTP JSON, JSON-RPC, or CDP traffic; they are not model usage. Direct CDP has no agent-facing task-text interface.
Browser RSS sums browser process memory, can double-count shared pages, and excludes daemons. Timing and protocol captures use separate runs. These results come from one machine, one browser build, and one run date (2026-09-11) measuring deterministic browser primitives, not agent task completion or general speed; see the canonical methodology caveats, which must accompany these figures wherever they are quoted. Raw samples, methodology, discovery costs, and feature comparison.
Browser | Version | Result |
Firefox | 155.0.1 | Passed |
Chrome | 151.0.7922.47 | Passed |
Zen | 1.22b | Passed |
Helium | 0.17.0.1 (Chromium 153.0.8010.36) | Passed |
The Chrome check used Google Chrome for Testing, the automation distribution of Chrome. Its exact version is shown above.
Contribute
Build and test · Changelog · Third-party notices · Privacy · Security · MIT license · Sponsorship
Directory | Contents |
| Browser manifests, page handlers, popup, icons |
| HTTP/WebSocket relay and MCP server |
| CLI, recipes, adapter support |
| Agent instructions |
| Recipes and extraction schemas |
| Behavioral, transport, and package checks |
Star history
Python package build (PyPI)
The browser extension release workflow is separate from Python packaging. Python package metadata is in pyproject.toml; uv.lock governs development. Run uv lock --check, uv sync --locked, and uv build to produce an sdist and wheel in dist/. After the owner approves a release and PyPI credentials/trusted publishing are configured, uv publish can upload those artifacts. Do not treat building as release authorization.
Available Tools
49 toolssleeper_apiC
Call page backend API with captured auth token (background fetch)
Inputs: url (required), body, method, profile.
sleeper_backD
History back
Inputs: tab, profile.
sleeper_batchB
Run ordered browser actions in one request; stops at the first failure by default
Inputs: actions (required), profile, stop_on_error.
sleeper_checkC
Check checkbox
Inputs: selector (required), tab, profile.
sleeper_clickC
Click element by CSS selector (supports :has-text)
Inputs: selector (required), tab, profile.
sleeper_click_allC
Click every matching element
Inputs: selector (required), tab, profile.
sleeper_click_textC
Click element by text
Inputs: text (required), tab, exact, index, +2 more.
sleeper_consoleD
Page console capture
Inputs: tab, limit, profile.
sleeper_dblclickC
Double-click element
Inputs: selector (required), tab, profile.
sleeper_dialogC
Install auto accept/dismiss dialog hook
Inputs: profile.
sleeper_dragC
Drag source to target
Inputs: source (required), target (required), tab, profile.
sleeper_execC
Execute arbitrary JS in Chromium; unavailable in signed Firefox builds
Inputs: code (required), tab, profile.
sleeper_extractD
Extract selector->text map
Inputs: map (required), tab, profile.
sleeper_fill_formC
Fill form by name/id/placeholder (JSON map)
Inputs: fields (required), tab, profile.
sleeper_findC
Inspect elements by CSS selector
Inputs: selector (required), tab, profile.
sleeper_find_textC
Find element by innerText
Inputs: text (required), tab, exact, profile.
sleeper_focusD
Focus element
Inputs: selector (required), tab, profile.
sleeper_formsC
Enumerate form inputs
Inputs: tab, profile, selector.
sleeper_framesC
List cross-origin iframes
Inputs: profile.
sleeper_getC
Get page/element properties
Inputs: tab, profile, selector.
sleeper_gotoC
Navigate to URL
Inputs: url (required), tab, profile.
sleeper_hoverD
Mouseover element
Inputs: selector (required), tab, profile.
sleeper_keysC
Dispatch key events on active element
Inputs: keys (required), tab, profile.
sleeper_mediaC
Per-tab media request log
Inputs: tab, clear, since, profile.
sleeper_networkD
Per-tab request log or fetch
Inputs: tab, url, body, clear, +5 more.
sleeper_newtabC
Open new tab via extension API
Inputs: url (required), profile.
sleeper_pressC
Keyboard events on element/active
Inputs: key (required), tab, profile, selector.
sleeper_readC
Read single element (text/html/value/attr)
Inputs: selector (required), tab, attr, what, +1 more.
sleeper_read_allC
Read all matching elements
Inputs: selector (required), tab, attr, what, +1 more.
sleeper_screenshotC
Alias for shot — viewport PNG screenshot
Inputs: tab, profile.
sleeper_scrollC
Scroll by pixels or to selector
Inputs: y, tab, profile, selector.
sleeper_scroll_untilC
Scroll until text/selector appears
Inputs: tab, text, profile, selector, +2 more.
sleeper_selectC
Set select value + change event
Inputs: value (required), selector (required), tab, profile.
sleeper_sessionsB
List connected stable browser installation IDs for routing
Inputs: profile.
sleeper_shotC
Viewport PNG screenshot (data URL)
Inputs: tab, profile.
sleeper_snapshotC
Headings/inputs/buttons/links summary
Inputs: tab, profile.
sleeper_stateB
Get page state for the selected Sleeper profile (url, title, focus, visibility)
Inputs: profile.
sleeper_submitC
Submit form
Inputs: tab, profile, selector.
sleeper_tabsB
List tabs in the selected Sleeper browser profile
Inputs: profile.
sleeper_typeC
Type into input (React-compatible events)
Inputs: text (required), selector (required), tab, clear, +2 more.
sleeper_uncheckC
Uncheck checkbox
Inputs: selector (required), tab, profile.
sleeper_uploadB
Upload explicit base64 file contents to an input; native paths are unsupported. Total JSON request limit: 1 MiB.
Inputs: files (required), selector (required), tab, profile.
sleeper_waitD
Wait for selector
Inputs: selector (required), tab, profile, timeout.
sleeper_wait_dialogD
Wait for dialog
Inputs: tab, text, profile, timeout_ms.
sleeper_wait_downloadC
Wait for a download matching a URL/filename pattern to finish
Inputs: pattern (required), tab, profile, timeout_ms.
sleeper_wait_textD
Wait for text
Inputs: text (required), tab, exact, profile, +1 more.
sleeper_wait_untilC
Wait for a structured page condition; JavaScript predicates are Chromium-only
Inputs: tab, profile, timeout, interval, +2 more.
sleeper_wait_urlC
Wait until URL contains pattern
Inputs: pattern (required), tab, profile, timeout_ms.
sleeper_wait_xhrC
Wait for XHR matching URL substring
Inputs: url_substring (required), tab, method, profile, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 49 tools
Descriptions generally clarify boundaries, but several clusters overlap heavily: element reading (get, find, find_text, read, read_all, extract) and clicking (click, click_text, click_all) require careful reading to pick correctly, and shot/screenshot are literal aliases. press vs keys vs type also border on each other.
Nearly all tools follow a consistent sleeper_ prefix with lowercase snake_case verb or verb_noun names (goto, click_text, wait_url), which is highly predictable. Minor deviations like the shot/screenshot alias and single-word verbs slightly break the pattern.
49 tools is well above a comfortable range for a single server and includes redundant entries (shot/screenshot alias, multiple near-duplicate click/read/find variants). The surface could be consolidated substantially without losing capability.
Coverage of browser automation is broad: navigation, interaction, waiting, forms, uploads, dialogs, tabs, frames, network/console capture, and screenshots. Only some gaps remain (e.g. cookie/storage management), but core workflows are fully supported.
Maintenance
Related MCP Connectors
Connect your agents to any website. The cheaper, faster and more reliable alternative to browser use
Let your AI agent operate any website through a real, logged-in browser session.
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
AI-powered browser automation — navigate, click, fill forms, and extract data from any website.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to control the user's Chrome or Firefox browser, leveraging existing sessions for tasks requiring authentication and user handoff.1847 npm21MIT
- FlicenseBqualityBmaintenanceEnables AI agents to control existing Chrome and Firefox browser sessions locally, including tab management, navigation, form filling, screenshots, and persistent scripts, without remote relays or debugging ports.36-
- AlicenseNot gradedqualityBmaintenanceEnables any coding agent to use the user's existing Chrome profiles and logins to open tabs, read pages, fill forms, click through flows, and take screenshots.81 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to control a real, authenticated Chrome browser through native tools for navigation, DOM interaction, form filling, scraping, screenshots, and human-in-the-loop checkpoints while minimizing tokens and latency.MIT