webclaw

WebClaw is a WebMCP-native browser agent that runs inside a real Chrome instance via a Chrome extension. It enables an MCP client (such as Claude, Cursor, or VS Code with WebMCP) to control a live Chrome session with access to logged-in sessions, cookies, and extensions. The MCP server exposes a set of 21 tools for page interaction, navigation, and WebMCP tool discovery/invocation, enabling the AI to navigate, inspect, and manipulate web pages through a compact accessibility tree rather than raw DOM coordinates.

Typical workflows involve starting the MCP server, then using your MCP client to call tools like navigate_to, page_snapshot, click, type_text, and select_option. You can also discover and invoke page-declared WebMCP tools via list_webmcp_tools and invoke_webmcp_tool. The extension communicates results back to the MCP server over WebSocket, and the AI can reference stable @ref labels to interact with page elements.

Prerequisites:

• Node.js and npm (or npx available via npm install)
• Optional: pnpm (recommended for building the extension repository)

1. Install Node.js and npm

• Visit https://nodejs.org/ and install the LTS version for your OS.

2. Install pnpm (optional but recommended for building)

• npm install -g pnpm

3. Clone the WebClaw repository

• git clone https://github.com/kuroko1t/webclaw.git
• cd webclaw

4. Install dependencies and build

• pnpm install
• pnpm build

5. Run the MCP server (via npx as configured by mcp_config)

• Ensure the environment variable WEBCLAW_PORT is set if you need a non-default port (default is 18080).
• Start the MCP server using the configuration described in mcp_config (the server will listen for MCP client connections and forward commands to the Chrome extension).

6. Load the Chrome extension (manual step outlined in Quick Start)

• Load the built extension from packages/extension/dist/ as described in the README.

Tips and common issues:

• The MCP server uses a real Chrome extension, so the agent has access to cookies, logged-in sessions, and extensions. This provides robust bot resistance but requires a proper extension load in Chrome.
• WebSocket port range 18080–18089 is scanned automatically for multi-session support; WEBCLAW_PORT can be tuned to avoid conflicts when running multiple MCP server instances.
• If you encounter connection issues between the MCP server and the extension, verify that the extension is loaded and the dist/ folder is served correctly by the extension, and ensure the WebSocket endpoint is reachable from the MCP client.
• When using Claude Code, Cursor, or VS Code, follow the exact JSON/YAML/mcp_config formats shown in the Quick Start to register the webclaw MCP server.
• The 21 MCP tools include page interaction (navigate_to, page_snapshot, click, hover, type_text, etc.), tab management, navigation controls, and WebMCP tool discovery/invocation for on-page tools.