kuroko1t/webclaw

22 stars 0 forks Quality 65 Trend 31

A WebMCP-native browser agent that runs inside your real Chrome — control it from Claude, Cursor, and any MCP client

Overview

A browser agent that runs inside your real Chrome — control it from Claude, Cursor, and any MCP client. WebClaw runs as a , so it sees exactly what you see — cookies, logins, extensions, and all. No headless browser, no CDP injection, no bot flags. Config file locations: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Linux: ~/.config/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json Add to .cursor/mcp.json in your project root: Add to .vscode/mcp.json in your project root: Add to ~/.codeium/windsurf/mcp_config.json: 1. Download the latest webclaw-extension.zip from the Releases page and unzip 2. Open chrome://extensions/ → enable 3. Click → select the dist/ folder Then load packages/extension/dist/ as above.

README

WebClaw

A WebMCP-native browser agent that runs inside your real Chrome — control it from Claude, Cursor, and any MCP client.

Why WebClaw?

	WebClaw	browser-use	Playwright MCP
Runs in real Chrome	Yes (extension)	No (CDP)	No (Playwright)
User’s logged-in sessions	Yes	No	No
Bot detection	Resistant	Vulnerable	Vulnerable
WebMCP native tools	Yes	No	No
Page understanding	`@ref` a11y tree	Screenshots	DOM / Screenshots

WebClaw runs as a Chrome extension, so it sees exactly what you see — cookies, logins, extensions, and all. No headless browser, no CDP injection, no bot flags.

Quick Start

1. Configure your MCP client

2. Load the Chrome extension

Download the latest webclaw-extension.zip from the Releases page and unzip
Open chrome://extensions/ → enable Developer mode
Click Load unpacked → select the dist/ folder

3. Try it

Restart your MCP client and ask:

“Go to wikipedia.org and search for Model Context Protocol”

Chrome launches automatically on the first tool call. The Side Panel shows all activity in real-time.

How It Works

flowchart LR
    LLM["AI Assistant"]
    MCP["MCP Server"]
    EXT["Chrome Extension"]
    CS["Content Script"]

    LLM -- "stdio" --> MCP -- "WebSocket" --> EXT --> CS

    style LLM fill:#7b2d8b,stroke:#333,color:#fff
    style MCP fill:#1a5276,stroke:#333,color:#fff
    style EXT fill:#1e8449,stroke:#333,color:#fff
    style CS fill:#b7950b,stroke:#333,color:#fff

The AI calls MCP tools (navigate_to, page_snapshot, click, …)
The MCP server forwards requests to the Chrome extension via WebSocket
The content script reads the page as a compact accessibility tree with @ref labels
The AI picks the right @ref and acts — no pixel coordinates, no CSS selectors

`page_snapshot` output

[page "Wikipedia, the free encyclopedia"]
  [search]
    [form]
      [@e3 searchbox "Search Wikipedia"]    ← AI targets this
      [@e4 button "Search"]                 ← and clicks this
  [main]
    [heading[1] "Welcome to Wikipedia"]
    [group]
      [heading[2] "From today's featured article"]
      ...

Every interactive element gets a stable @ref label. The AI reads the tree, picks the right @ref, and calls click / type_text / select_option.

MCP Tools (21)

Development

git clone https://github.com/kuroko1t/webclaw.git
cd webclaw
pnpm install
pnpm build        # Build all packages
pnpm test         # Run all tests
pnpm dev          # Watch mode

Project Structure

packages/
  shared/          Type definitions, Zod schemas, utilities
  mcp-server/      MCP server with 21 tools, WebSocket bridge
  extension/       Chrome MV3 extension (service worker, content scripts, side panel)
examples/
  webmcp-demo-site/  WebMCP-enabled Todo app for testing native tool discovery

Multi-Session Support

WebClaw automatically scans ports 18080–18089, so you can run up to 10 MCP server instances simultaneously (e.g., multiple Claude Code sessions). Each instance binds to the first available port, and the Chrome extension connects to all of them.

Environment Variables

Variable	Default	Description
`WEBCLAW_PORT`	`18080`	WebSocket port for MCP server ↔ extension communication. When set, disables auto-scanning and uses only this port.

Contributing

Contributions are welcome! Please open an issue to discuss your idea before submitting a pull request.

Disclaimer

WebClaw is a browser automation tool intended for legitimate use cases such as personal productivity, development, testing, and accessibility. Users are responsible for complying with the terms of service of any website they interact with. The authors are not responsible for any misuse of this tool.

License

MIT

View the full README on GitHub

Install

npx -y webclaw-mcp

New to MCP? Start with the mcpskill.org guide →

Configuration

{
  "mcpServers": {
    "webclaw": {
      "command": "npx",
      "args": ["-y", "webclaw-mcp"]
    }
  }
}