# ecobrowser [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/HaidarESBER/ai-browser  
**GitHub Stars:** 1  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ecobrowser

## Description
AI-native browser framework — the AI's hands and eyes on the web. Structured (no-pixel) perception, verified self-healing actions, incremental diff perception, a live view — as a TypeScript library and an MCP server.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "ecobrowser": {
    "command": "npx",
    "args": ["-y","ecobrowser-mcp"],
    "env": {
      "AI_BROWSER_HEADED": "",
      "PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD": ""
    }
  }
}
```

**Requires environment variables:** `AI_BROWSER_HEADED`, `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What ecobrowser does

ecobrowser connects an MCP client to a Chromium browser driven through Playwright. Its primary interface is a set of schema-defined MCP tools exposed over JSON-RPC 2.0 through stdio. The same browser engine is also available as a TypeScript library, so applications can use the browser directly instead of going through MCP.

Rather than returning a screenshot as the main page representation, the engine produces a compact inventory of interactive elements. Entries include durable IDs along with information such as role, accessible name, value, state, and available options. Agents can use those IDs to click, type, or select without constructing CSS selectors or relying on pixel coordinates.

## How it works

The engine inspects each frame and open shadow root, then tracks DOM changes with a mutation observer. Unchanged snapshots can be served from cache, while `changes()` reports only the difference since the previous observation. `find(description)` can narrow a request such as “the search box” to a matching element.

Actions include a verification step that reports whether the operation succeeded and whether the page changed. If an element ID no longer resolves after a re-render, ecobrowser attempts to locate the same element by its identity. It avoids retrying an operation that may already have been applied, such as a click whose handler stalled, and reports that uncertain state as `maybeApplied`.

The engine handles ARIA widgets, contenteditable controls, iframes, open shadow DOM, dropdown options, and elements covered by another element. New tabs opened by links are reported, and the MCP server switches to the new tab. Password values are represented as `[redacted]` rather than captured.

## Setup and configuration

Install the npm package with Node.js 18 or newer:

```bash
npm install ecobrowser
```

Chromium is downloaded by the package’s postinstall process. If installation scripts are disabled, browser downloading is skipped, or the machine is offline, install Chromium separately with `npx playwright install chromium`. To run the MCP entry point, use `npx -y ecobrowser-mcp`, or point a client at `src/mcp.ts` when working from a repository checkout.

Claude Desktop can start the server through its MCP configuration, and Claude Code can register it with `claude mcp add ecobrowser -- npx -y ecobrowser-mcp`. The `AI_BROWSER_HEADED` setting enables a headed browser. `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1` prevents Playwright from downloading Chromium.

## Tools and capabilities

The MCP adapter advertises 22 tools with JSON schemas. The documented interaction model includes navigation, structured snapshots, element lookup, clicking, typing, selecting, incremental changes, and browser diagnostics. Console output, page errors, and network requests are captured and associated with the action that produced them.

A separate live-view server provides a refreshed screenshot and color-coded action trace so a human can supervise the run. The browser is headless by default.

## Limitations and notes

ecobrowser is designed as a fast, local, single-user developer tool for sites that the operator owns or is authorized to access. Its behavior has been tested thoroughly along its own paths but is intended to be evaluated before use across broad collections of production websites. The live view is for observation; the MCP adapter remains the control interface.

_Full upstream README: https://allmcps.com/mcp/ecobrowser/readme_