Owl Browser MCP Server

MCP (Model Context Protocol) server for Owl Browser. Owl Browser is agent-native: instead of screenshots or raw HTML, it renders a page as OwlMark — a compact, handle-addressable view that is ~20–100× cheaper in tokens. The MCP server promotes this loop and advertises a profile-scoped, curated toolset, so a model (especially a smaller one) sees a short, focused tool list instead of a wall of 180 endpoints.

The agent-native loop

browser_create_context        # render_mode defaults to 'agent'
  → browser_navigate(url)
  → browser_observe            # compact OwlMark view + handle table (e.g. 'b3','l5','x2')
  → browser_click(handle) / browser_type(handle, text)
  → browser_observe            # see the result; repeat

browser_observe is the primary way to read a page. browser_screenshot is kept for visual confirmation of design/style. browser_expand / browser_read_node drill into a collapsed region or read a node's full text. Handle tokens from observe are passed directly to click/type — no CSS selectors needed.

Tool profiles

The tools advertised to the model are controlled by OWL_MCP_PROFILE (default agent). Every profile shares a lean CORE (the loop above + screenshot); broader profiles layer specialised tools on top.

| OWL_MCP_PROFILE | Tools | For | |---|---|---| | agent (default) | ~14 | The agent-native loop. Best for small models and general browsing — short list, low context cost. | | automation | ~29 | Broader interactive browsing: multi-tab, dialogs, cookies, uploads, forms, more waits. | | webdev | ~30 | Building/verifying web apps: JS eval, console & network logs, raw HTML/markdown, attributes, viewport, frames. | | full | ~70 | The complete agent-useful surface (prior behaviour) plus the agent-native tools. |

Infrastructure tools (video, streaming, license, CAPTCHA, profile/stealth, proxy, demographics, downloads, FTP, IPC tests, server-ops) are intentionally excluded from all profiles — use the REST API / SDKs for those.

Features

• Agent-native by default: create_context renders in agent mode; browser_observe returns a token-efficient, handle-addressable view.
• Profile-scoped tools: short, curated lists via OWL_MCP_PROFILE — no dumping 180 tools on the model.
• Multiple Contexts: create and manage isolated browser sessions.
• HTTP API Backend: connects to Owl Browser's HTTP server (Docker or standalone).

Installation

Via npx (recommended)

No installation needed - just configure Claude Desktop to use:

"command": "npx",
"args": ["-y", "@olib-ai/owl-browser-mcp"]

Global install

npm install -g @olib-ai/owl-browser-mcp

Then use in Claude Desktop config:

"command": "owl-browser-mcp"

From source

git clone https://github.com/Olib-AI/owl-browser-mcp
cd owl-browser-mcp
npm install
npm run build

Architecture: Understanding Ports

The Owl Browser exposes two ports with different purposes:

| Port | Service | Description | |------|---------|-------------| | 80 | Nginx Proxy | Web control panel + API gateway. Recommended for Docker deployments. Routes /api/*, /execute/*, /ws to the HTTP server. | | 8080 | HTTP Server | Direct REST API access. Use for standalone (non-Docker) deployments or debugging. |

Important: When using Docker, connect to port 80 (nginx), not port 8080. The nginx proxy handles routing, authentication, and serves the web control panel.

┌─────────────────┐         ┌─────────────────────────────────────┐
│   MCP Server    │         │           Docker Container          │
│                 │  HTTP   │  ┌─────────┐      ┌──────────────┐  │
│ OWL_API_ENDPOINT├────────►│  │  Nginx  │─────►│ HTTP Server  │  │
│ = localhost:80  │         │  │ (port 80)│      │ (port 8080)  │  │
└─────────────────┘         │  └─────────┘      └──────────────┘  │
                            └─────────────────────────────────────┘

Configuration

Set environment variables before running:

| Variable | Description | Default | |----------|-------------|---------| | OWL_API_ENDPOINT | HTTP API endpoint URL (raw server :8080 or nginx :80 — both work) | http://127.0.0.1:8080 | | OWL_API_TOKEN | Bearer token for authentication (same as OWL_HTTP_TOKEN in Docker) | (none) | | OWL_MCP_PROFILE | Which curated toolset to advertise: agent | automation | webdev | full (see Tool profiles) | agent |

Example — expose the broader web-development toolset:

"env": {
  "OWL_API_ENDPOINT": "http://localhost:80",
  "OWL_API_TOKEN": "your-api-token",
  "OWL_MCP_PROFILE": "webdev"
}

Usage with Docker (Recommended)

When using the Owl Browser Docker image, connect to port 80 (nginx proxy):

{
  "mcpServers": {
    "owl-browser": {
      "command": "npx",
      "args": ["-y", "@olib-ai/owl-browser-mcp"],
      "env": {
        "OWL_API_ENDPOINT": "http://localhost:80",
        "OWL_API_TOKEN": "your-api-token"
      }
    }
  }
}

Or if Docker is running on a remote host:

{
  "mcpServers": {
    "owl-browser": {
      "command": "npx",
      "args": ["-y", "@olib-ai/owl-browser-mcp"],
      "env": {
        "OWL_API_ENDPOINT": "http://your-docker-host:80",
        "OWL_API_TOKEN": "your-api-token"
      }
    }
  }
}

Note: The OWL_API_TOKEN must match the OWL_HTTP_TOKEN environment variable set when starting the Docker container.

Usage with Standalone HTTP Server

If running the HTTP server directly (without Docker/nginx), connect to port 8080:

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "owl-browser": {
      "command": "npx",
      "args": ["-y", "@olib-ai/owl-browser-mcp"],
      "env": {
        "OWL_API_ENDPOINT": "http://127.0.0.1:8080",
        "OWL_API_TOKEN": "your-api-token"
      }
    }
  }
}

Local Development

If running from source instead of npm:

{
  "mcpServers": {
    "owl-browser": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"],
      "env": {
        "OWL_API_ENDPOINT": "http://127.0.0.1:80",
        "OWL_API_TOKEN": "your-api-token"
      }
    }
  }
}

Available Tools

The advertised tools depend on OWL_MCP_PROFILE (see Tool profiles). The default agent profile exposes the ~14-tool CORE; broader profiles add to it.

CORE — the agent-native loop (every profile)

• browser_create_context — create an isolated session (defaults to render_mode='agent')
• browser_close_context — close a session
• browser_navigate — go to a URL
• browser_go_back — history back
• browser_observe — primary page read: compact OwlMark view + handle table
• browser_expand — re-serialize one collapsed region/template at higher detail
• browser_read_node — read a node's full uncompacted text/value/attributes
• browser_click — click by handle token (CSS / coordinates / NL also accepted)
• browser_type — type into an input by handle token
• browser_clear_input — clear an input before re-typing
• browser_press_key — press a key (Enter, Tab, …)
• browser_scroll_to_element — bring an element into view
• browser_wait — wait for a duration / condition
• browser_screenshot — PNG for visual confirmation of design/style

automation adds (~29 total)

Multi-tab (get_tabs, switch_tab, new_tab, close_tab), dialogs (handle_dialog), cookies (get_cookies, set_cookie), upload_file, submit_form, keyboard_combo, reload, go_forward, list_contexts, scroll_to_bottom, wait_for_selector.

webdev adds (~30 total)

evaluate, get_console_log, clear_console_log, get_html, get_markdown, extract_text, get_network_log, enable_network_logging, get_headers, get_attribute, is_visible, set_viewport, highlight, list_frames, switch_to_frame, switch_to_main_frame.

full (~70 total)

Everything above plus the remaining agent-useful tools (element-state checks, pick, focus, select_all, find_element, additional scroll/wait variants, get_page_map, get_page_info, http_request, WebMCP page-declared tools). Infrastructure tools (video, license, CAPTCHA, proxy, profile/stealth, demographics, downloads, FTP) are not exposed via MCP — use the REST API / SDKs.

Protocol Version

This server implements MCP protocol version 2025-11-25.

Testing with MCP Inspector

Use the official MCP Inspector to test the server interactively.

Run from the mcp-server directory:

cd mcp-server

# With Docker container (connect to nginx on port 80)
npx @modelcontextprotocol/inspector \
  -e OWL_API_ENDPOINT=http://localhost:80 \
  -e OWL_API_TOKEN=your-docker-token \
  node dist/index.js

# With standalone HTTP server (connect directly to port 8080)
npx @modelcontextprotocol/inspector \
  -e OWL_API_ENDPOINT=http://127.0.0.1:8080 \
  -e OWL_API_TOKEN=your-token \
  node dist/index.js

# With remote Docker server
npx @modelcontextprotocol/inspector \
  -e OWL_API_ENDPOINT=http://your-server.com:80 \
  -e OWL_API_TOKEN=your-api-token \
  node dist/index.js

The Inspector will open a web UI (default: http://localhost:6274) where you can:

• Browse the active profile's tools (set OWL_MCP_PROFILE to change which are listed)
• Execute tools with custom parameters
• View JSON responses in real-time

Development

# Install dependencies
npm install

# Build ESM version
npm run build

# Build CommonJS version
npm run build:cjs

# Run in development mode
npm run dev

Output Files

• dist/index.js - ESM bundle (~887KB, single file with embedded schema)
• dist/index.cjs - CommonJS bundle (~887KB, single file with embedded schema)

Both bundles are self-contained and include the OpenAPI schema embedded at build time.