Skills

octop-browser: Make Your Agent's Browser Operations More Accurate and Reliable

octop-browser is best for letting MCP-capable agents complete browser automation more accurately and reliably through real Chromium. Before use, you must accept that it downloads a Chromium binary (possibly one-time bootstrapping Playwright) and adopt the dom-tree→ref safe locating pattern.

Official source · TencentCloud/octop-browser

Install

pip install octop-browser
octop-browser install-browser

Who It's For

  • Users who already work with MCP-capable agents (such as Claude, Cursor, or other clients that can configure MCP servers) and want their agent to operate a real browser more accurately and reliably.
  • Scenarios that require headless or real Chromium automation, such as opening web pages, reading the DOM, performing clicks and form actions, and other browser tasks.
  • Requires a Python 3.11+ environment with pip available.
  • Not for: users unsure whether their agent supports MCP — the official documentation states it connects as a built-in MCP server (MCP over stdio), which depends on the agent having MCP capability; other integration methods are not covered by the evidence. Also note it requires a Chromium binary to be installed on your machine.

Your First Try in 3 Minutes

Recommended main path (the officially documented installation method):

  1. Prerequisites: Python 3.11+, pip available.
  2. Install and download the browser binary:
pip install octop-browser
octop-browser install-browser
  1. Configure octop-browser's MCP server in your agent client, so the agent drives the browser through the same set of tools.
  2. Trigger a low-risk task: have the agent run a read-only DOM check via browser_tool(action=...). The officially recommended safe pattern is: before every click, first run dom-tree to obtain a stable reference (ref), then pass the ref to locate the element. For your first attempt, it is recommended to only run read-only check actions like dom-tree — no clicks or submissions.
  3. Success signal: after the agent invokes the dom-tree action and gets back the target page's DOM tree / element references, the browser is running and the CDP connection is working correctly.

Side-effect reminder: install-browser downloads a Chromium binary and may one-time bootstrap the installation of Playwright — this is only used to download Chromium; Playwright is not a runtime dependency. Please confirm you accept this download before installing.

Use Cases

Case 1: Have your agent inspect web page content. Scenario: you want to know a page's current DOM structure or whether a specific element exists. Send a task to the agent, for example, "use browser_tool's dom-tree action to open the sample page and list the main elements." The agent will return element references (refs), which you can use to decide whether subsequent clicks or interactions are needed — and the official recommendation is precisely to run dom-tree first and pass the ref before every click.

Case 2: Have your agent perform browser operations with a persistent login state. Scenario: you need to repeatedly operate on a site where you're already logged in. The official documentation supports reusing named profiles; a persistent profile saves login state on disk. You can have the agent open the site with a profile and complete login (note: logging in involves submitting credentials to an external website, an action with external side effects that should be confirmed with you before execution), after which subsequent sessions can reuse that profile's login state. Within the scope of the evidence, the profile mechanism and the dom-tree→ref locating flow can be confirmed; the login flow details for any specific site are not covered in the official documentation.

Usage Boundaries

  • Network / side effects: browser automation accesses external websites; actions like clicks and submissions change page state. The official recommendation is the "dom-tree first, then pass ref" pattern to reduce the risk of misfires. For your first attempt, stick to read-only checks.
  • Local side effects: install-browser downloads Chromium and may one-time bootstrap Playwright (only for the download, not a runtime dependency); persistent profiles save login state on disk — mind local privacy.
  • Integration surface: all operations can be executed via CLI commands or invoked by MCP agents through the built-in MCP server (stdio). The official documentation does not specify which clients are supported, nor how non-MCP agents can integrate.
  • Language / platform boundaries: the official documentation does not state the range of supported web page languages or operating system details; this information is unknown and no assumptions are made.
  • Not yet confirmed: the complete list of all roughly 20 actions, the exact format of MCP server configuration parameters, etc. Please defer to the official README before use.