Install MCP Server

Prerequisites

Node.js v18 or later.

Quick setup

npx -y crawlio-browser init

The init wizard:

1. Detects your AI clients: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Cline, Copilot CLI, Gemini CLI, Codex CLI, Goose, OpenCode, Zed
2. Configures each client with the correct MCP server entry
3. Installs the browser-automation skill for Claude Code

Open your AI client and the browser tools are available.

Manual setup

If the init wizard did not detect your client, add the config manually.

Claude Code

claude mcp add crawlio-browser -- npx -y crawlio-browser

{
  "mcpServers": {
    "crawlio-browser": {
      "command": "npx",
      "args": ["-y", "crawlio-browser"]
    }
  }
}

{
  "mcpServers": {
    "crawlio-browser": {
      "command": "npx",
      "args": ["-y", "crawlio-browser"]
    }
  }
}

{
  "mcpServers": {
    "crawlio-browser": {
      "command": "npx",
      "args": ["-y", "crawlio-browser"]
    }
  }
}

{
  "cline.mcpServers": {
    "crawlio-browser": {
      "command": "npx",
      "args": ["-y", "crawlio-browser"]
    }
  }
}

{
  "mcpServers": {
    "crawlio-browser": {
      "command": "npx",
      "args": ["-y", "crawlio-browser"]
    }
  }
}

Two browser modes

The MCP server connects to browsers in two ways.

Chrome extension (live browser)

The Chrome extension writes bridge info to ~/.crawlio/bridge/. The MCP server reads it and connects via WebSocket at 127.0.0.1:9333. This gives your AI control of your existing Chrome tabs, with your sessions, cookies, and login state intact.

96 tools. Install from the Chrome Web Store. See Install Chrome Extension.

Headless agent (background browser)

A Node.js process with embedded Chromium. Starts automatically when needed. No Chrome required.

~199 tools across 5 tiers:

The headless agent is bundled with the Direct distribution channel. For npm installs, it is included in @crawlio/mcp.

Routing

You do not need to choose a mode. The aggregator routes automatically: if a Chrome tab is connected, tools go to the extension. If not, they go to the headless agent. See Browser Agent Overview for details.

Config templates

Bundled variant (written by "Install MCP" in Crawlio Settings, includes all three pillars):

{
  "mcpServers": {
    "crawlio": {
      "command": "Crawlio.app/Contents/MacOS/CrawlioMCP"
    },
    "crawlio-browser": {
      "command": "node",
      "args": ["~/.crawlio/bridge/dist/mcp-server/index.js"]
    },
    "crawlio-agent-headless": {
      "command": "node",
      "args": ["~/.crawlio/agent-headless/index.js"]
    }
  }
}

npm variant (aggregator handles all pillars through a single entry):

{
  "mcpServers": {
    "crawlio": {
      "command": "npx",
      "args": ["@crawlio/mcp"]
    }
  }
}

Code mode (default)

By default, the server starts in code mode, collapsing 96 tools into 3 for ~95% schema token reduction:

See Code Mode for the search-and-execute pattern.

Full mode

To expose all 96 tools individually, add --full:

{
  "mcpServers": {
    "crawlio-browser": {
      "command": "npx",
      "args": ["-y", "crawlio-browser", "--full"]
    }
  }
}

Troubleshooting

Next steps

• Install the Chrome extension
• Start automating
• Browser Tools Reference