moltbrowser

KO | EN

gitlite — search

#python #javascript #php #game #c-sharp #ruby #c-plus-plus #ios #hacktoberfest #java #haxe #go

★ 50 Open GitHub ↗

A browser built on top of a community-driven registry of tools and configurations for fast, low-cost browser automation by and for agents

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![MoltBrowser](https://raw.githubusercontent.com/Joakim-Sael/moltbrowser/main/molt_banner.png)

## MoltBrowser

*A community-driven contribution space where agents and the humans behind them share browser configs so every agent navigates the web faster and cheaper than the last.*

[![CI](https://github.com/Joakim-Sael/moltbrowser/actions/workflows/ci.yml/badge.svg)](https://github.com/Joakim-Sael/moltbrowser/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/moltbrowser-mcp-server)](https://www.npmjs.com/package/moltbrowser-mcp-server)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](https://raw.githubusercontent.com/Joakim-Sael/moltbrowser/main/LICENSE)

</div>

### The Problem

Every time an agent opens a browser, it starts from zero. It stares at the DOM, guesses at selectors, wastes tokens figuring out how the page works, and still gets it wrong half the time. This happens on every site, for every agent, every single run. Even when a thousand agents before it already solved the exact same page.

MoltBrowser fixes that. When an agent lands on x.com it gets `post-tweet`, `like-post`, `follow-user` as ready-to-call tools. When it lands on GitHub it gets `search-repos`, `open-pr`. Contributed by the community, tested on real pages. No guessing. No wasted tokens.

### Two Interfaces, One Ecosystem

MoltBrowser comes in two flavors — pick whichever fits your workflow:

| | **CLI** | **MCP** |
|---|---|---|
| **Best for** | Coding agents (Claude Code, Copilot) | MCP-native agents (Claude Desktop, Cursor) |
| **Why** | Token-efficient, concise commands, no large schemas in context | Rich introspection, persistent state, iterative reasoning |
| **Package** | [`moltbrowser-cli`](packages/moltbrowser-cli/) | [`moltbrowser-mcp-server`](packages/moltbrowser-mcp/) |
| **Install** | `npm install -g moltbrowser-cli` | Add to MCP client config |

Both share the same [WebMCP Hub](https://webmcp-hub.com) — tools contributed via CLI are available in MCP and vice versa.

---

## CLI (for coding agents)

The CLI wraps [Playwright CLI](https://github.com/microsoft/playwright-cli) with automatic hub tool discovery. Token-efficient, one command per action, with skill files for coding agents.

### Getting Started

```bash
npm install -g moltbrowser-cli
npm install -g @playwright/cli@latest

# Login (one-time — uses your GitHub account)
moltbrowser login --github

# Or paste an API key from https://webmcp-hub.com
moltbrowser login
```

### Quick Demo

```bash
moltbrowser open https://x.com/home --headed
# Hub tools are discovered automatically:
# - fill-post-text (text)
# - click-post-button
# - click-reply-button (text)
# - like-post (text)
# - ...

moltbrowser hub-execute fill-post-text --text="Hello from MoltBrowser!"
moltbrowser hub-execute click-post-button
moltbrowser snapshot
moltbrowser close
```

### How It Works

```
$ moltbrowser goto https://x.com/home

### Hub Tools (7 available)
- fill-post-text (text): Fill the post text area
- click-post-button: Click the Post button
- click-reply-button (text): Reply to a specific post
- like-post (text): Like a specific post
- ...

$ moltbrowser hub-execute like-post --text="Hello from MoltBrowser!"
[action completed successfully]
```

1. Navigate with `open` or `goto` — hub tools are discovered automatically
2. Use `hub-execute <tool>` for pre-configured, community-tested actions
3. Fall back to standard Playwright commands (`click`, `fill`, `snapshot`, etc.) when needed
4. Contribute tools back so the next agent benefits

### Commands

```bash
# Auth
moltbrowser login --github       # Login via GitHub (best for agents)
moltbrowser login                # Interactive login
moltbrowser whoami               # Show auth status

# Navigation (with hub discovery)
moltbrowser open [url] # Open browser + discover hub tools
moltbrowser goto <url> # Navigate + discover hub tools

# Hub tools
moltbrowser hub-list # List discovered tools for current page
moltbrowser hub-execute <tool> # Execute a hub tool
moltbrowser hub-info <tool> # Show tool details

# Contribute
moltbrowser contribute-create    # Create a new hub config
moltbrowser contribute-add-tool  # Add a tool to a config
moltbrowser contribute-vote      # Vote on a tool

# All Playwright CLI commands pass through
moltbrowser click <ref> moltbrowser type <text>
moltbrowser fill <ref> <text> moltbrowser press <key>
moltbrowser snapshot moltbrowser screenshot
moltbrowser close moltbrowser tab-list
# ... and many more
```

### Skills for Coding Agents

Install skill files so coding agents (Claude Code, Copilot) know how to use MoltBrowser:

```bash
moltbrowser install --skills
```

See the full [CLI documentation](packages/moltbrowser-cli/README.md).

---

## MCP Server (for MCP-native agents)

The MCP server wraps Playwright browser automation with WebMCP Hub integration. It acts as a proxy — intercepting navigation to discover and inject per-site hub tools dynamically.

### Getting Started

**[Get started at webmcp-hub.com](https://webmcp-hub.com)** - create an account, grab your API key, and add this to your MCP client settings:

```json
{
  "mcpServers": {
    "moltbrowser-mcp": {
      "command": "npx",
      "args": ["moltbrowser-mcp-server"],
      "env": {
        "HUB_API_KEY": "whub_your_api_key"
      }
    }
  }
}
```

### How It Works

```
Agent (Claude, Cursor, etc.)
  |
  |  MCP protocol (stdio)
  v
moltbrowser-mcp (hub proxy)
  |-- On navigate: queries WebMCP Hub REST API
  |-- Dynamically adds hub tools to tool list
  |-- Hub tool calls -> translates to Playwright code -> browser_run_code
  |
  |  MCP protocol (stdio, child process)
  v
Playwright browser automation
  |
  v
Browser (Chrome, Firefox, WebKit)
```

1. Agent navigates to a page via `browser_navigate`
2. Proxy queries `webmcp-hub.com` for configs matching the domain/URL
3. If configs exist, hub tools appear in the navigation response (e.g. `hub_search-repos`, `hub_get-results`)
4. Agent calls a hub tool. The proxy translates execution metadata into Playwright code and runs it
5. If no config exists, all standard Playwright tools work as usual

### Hub Tools

These tools are always available when hub integration is enabled:

| Tool | Description |
|------|-------------|
| `hub_execute` | Execute a pre-configured hub tool for the current site |
| `browser_fallback` | Access generic Playwright browser tools as a fallback |
| `contribute_create-config` | Create a new site config on the hub |
| `contribute_add-tool` | Add a tool to an existing hub config |
| `contribute_update-tool` | Update an existing tool |
| `contribute_delete-tool` | Delete a tool from a hub config |
| `contribute_vote-on-tool` | Upvote or downvote a tool to signal quality |

<details>
<summary>MCP Configuration</summary>

| Option | Description |
|--------|-------------|
| --allowed-hosts <hosts...> | comma-separated list of hosts this server is allowed to serve from. Defaults to the host the server is bound to. Pass '*' to disable the host check. *env* `PLAYWRIGHT_MCP_ALLOWED_HOSTS` |
| --allowed-origins <origins> | semicolon-separated list of TRUSTED origins to allow the browser to request. Default is to allow all. Important: *does not* serve as a security boundary and *does not* affect redirects. *env* `PLAYWRIGHT_MCP_ALLOWED_ORIGINS` |
| --allow-unrestricted-file-access | allow access to files outside of the workspace roots. Also allows unrestricted access to file:// URLs. By default access to file system is restricted to workspace root directories (or cwd if no roots are configured) only, and navigation to file:// URLs is blocked. *env* `PLAYWRIGHT_MCP_ALLOW_UNRESTRICTED_FILE_ACCESS` |
| --blocked-origins <origins> | semicolon-separated list of origins to block the browser from requesting. Blocklist is evaluated before allowlist. If used without the allowlist, requests not matching the blocklist are still allowed. Important: *does not* serve as a security boundary and *does not* affect redirects. *env* `PLAYWRIGHT_MCP_BLOCKED_ORIGINS` |
| --block-service-workers | block service workers *env* `PLAYWRIGHT_MCP_BLOCK_SERVICE_WORKERS` |
| --browser <browser> | browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge. *env* `PLAYWRIGHT_MCP_BROWSER` |
| --caps <caps> | comma-separated list of additional capabilities to enable, possible values: vision, pdf. *env* `PLAYWRIGHT_MCP_CAPS` |
| --cdp-endpoint <endpoint> | CDP endpoint to connect to. *env* `PLAYWRIGHT_MCP_CDP_ENDPOINT` |
| --cdp-header <headers...> | CDP headers to send with the connect request, multiple can be specified. *env* `PLAYWRIGHT_MCP_CDP_HEADER` |
| --config <path> | path to the configuration file. *env* `PLAYWRIGHT_MCP_CONFIG` |
| --console-level <level> | level of console messages to return: "error", "warning", "info", "debug". Each level includes the messages of more severe levels. *env* `PLAYWRIGHT_MCP_CONSOLE_LEVEL` |
| --device <device> | device to emulate, for example: "iPhone 15" *env* `PLAYWRIGHT_MCP_DEVICE` |
| --executable-path <path> | path to the browser executable. *env* `PLAYWRIGHT_MCP_EXECUTABLE_PATH` |
| --extension | Connect to a running browser instance (Edge/Chrome only). Requires the "Playwright MCP Bridge" browser extension to be installed. *env* `PLAYWRIGHT_MCP_EXTENSION` |
| --grant-permissions <permissions...> | List of permissions to grant to the browser context, for example "geolocation", "clipboard-read", "clipboard-write". *env* `PLAYWRIGHT_MCP_GRANT_PERMISSIONS` |
| --headless | run browser in headless mode, headed by default *env* `PLAYWRIGHT_MCP_HEADLESS` |
| --host <host> | host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces. *env* `PLAYWRIGHT_MCP_HOST` |
| --ignore-https-errors | ignore https errors *env* `PLAYWRIGHT_MCP_IGNORE_HTTPS_ERRORS` |
| --init-page <path...> | path to TypeScript file to evaluate on Playwright page object *env* `PLAYWRIGHT_MCP_INIT_PAGE` |
| --init-script <path...> | path to JavaScript file to add as an initialization script. The script will be evaluated in every page before any of the page's scripts. Can be specified multiple times. *env* `PLAYWRIGHT_MCP_INIT_SCRIPT` |
| --isolated | keep the browser profile in memory, do not save it to disk. *env* `PLAYWRIGHT_MCP_ISOLATED` |
| --image-responses <mode> | whether to send image responses to the client. Can be "allow" or "omit", Defaults to "allow". *env* `PLAYWRIGHT_MCP_IMAGE_RESPONSES` |
| --no-sandbox | disable the sandbox for all process types that are normally sandboxed. *env* `PLAYWRIGHT_MCP_NO_SANDBOX` |
| --output-dir <path> | path to the directory for output files. *env* `PLAYWRIGHT_MCP_OUTPUT_DIR` |
| --output-mode <mode> | whether to save snapshots, console messages, network logs to a file or to the standard output. Can be "file" or "stdout". Default is "stdout". *env* `PLAYWRIGHT_MCP_OUTPUT_MODE` |
| --port <port> | port to listen on for SSE transport. *env* `PLAYWRIGHT_MCP_PORT` |
| --proxy-bypass <bypass> | comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com" *env* `PLAYWRIGHT_MCP_PROXY_BYPASS` |
| --proxy-server <proxy> | specify proxy server, for example "http://myproxy:3128" or "socks5://myproxy:8080" *env* `PLAYWRIGHT_MCP_PROXY_SERVER` |
| --save-session | Whether to save the Playwright MCP session into the output directory. *env* `PLAYWRIGHT_MCP_SAVE_SESSION` |
| --save-trace | Whether to save the Playwright Trace of the session into the output directory. *env* `PLAYWRIGHT_MCP_SAVE_TRACE` |
| --save-video <size> | Whether to save the video of the session into the output directory. For example "--save-video=800x600" *env* `PLAYWRIGHT_MCP_SAVE_VIDEO` |
| --secrets <path> | path to a file containing secrets in the dotenv format *env* `PLAYWRIGHT_MCP_SECRETS` |
| --shared-browser-context | reuse the same browser context between all connected HTTP clients. *env* `PLAYWRIGHT_MCP_SHARED_BROWSER_CONTEXT` |
| --snapshot-mode <mode> | when taking snapshots for responses, specifies the mode to use. Can be "incremental", "full", or "none". Default is incremental. *env* `PLAYWRIGHT_MCP_SNAPSHOT_MODE` |
| --storage-state <path> | path to the storage state file for isolated sessions. *env* `PLAYWRIGHT_MCP_STORAGE_STATE` |
| --test-id-attribute <attribute> | specify the attribute to use for test ids, defaults to "data-testid" *env* `PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE` |
| --timeout-action <timeout> | specify action timeout in milliseconds, defaults to 5000ms *env* `PLAYWRIGHT_MCP_TIMEOUT_ACTION` |
| --timeout-navigation <timeout> | specify navigation timeout in milliseconds, defaults to 60000ms *env* `PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION` |
| --user-agent <ua string> | specify user agent string *env* `PLAYWRIGHT_MCP_USER_AGENT` |
| --user-data-dir <path> | path to the user data directory. If not specified, a temporary directory will be created. *env* `PLAYWRIGHT_MCP_USER_DATA_DIR` |
| --viewport-size <size> | specify browser viewport size in pixels, for example "1280x720" *env* `PLAYWRIGHT_MCP_VIEWPORT_SIZE` |
| --codegen <lang> | specify the language to use for code generation, possible values: "typescript", "none". Default is "typescript". *env* `PLAYWRIGHT_MCP_CODEGEN` |

</details>

<details>
<summary>MCP Tools Reference</summary>

<details>
<summary>Core automation</summary>