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.

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

Headless agent (background browser)

A bundled Node.js process that launches an installed Google Chrome, Chromium, or Chrome Canary executable without a visible window. The browser itself is not bundled and must be installed before using rendering tools. Crawlio discovers standard application locations; set CRAWLIO_CHROMIUM_PATH to the browser executable when it is installed elsewhere.

Preflight a standard Google Chrome installation with:

open -Ra "Google Chrome"

The headless agent is bundled with the Direct distribution channel. For npm installs, it is included in @crawlio/mcp. Both installation paths require a separately installed Chrome-family browser.

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 150 tools into 7 for about 85% smaller schema payload:

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

Full mode

To expose all 150 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