MCP Setup

Quick start

npx crawlio-mcp init

The wizard automatically:

Detects which AI clients are installed (Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Zed, Gemini CLI, and more)
Finds the CrawlioMCP binary (app bundle, Homebrew, npm cache, or builds from source)
Writes the correct config to each detected client
Installs 5 Claude Code skills for guided workflows
Prints a summary of what was configured

Init flags

Flag	Effect
`--full`	Configure for full mode (49 tools) instead of code mode (6 tools)
`--portal`	Set up HTTP transport + launchd auto-start service
`--dry-run`	Preview changes without writing anything
`--yes` / `-y`	Skip confirmation prompts
`--json`	Machine-readable output (used by Crawlio.app onboarding)

Examples

# Preview what would happen
npx crawlio-mcp init --dry-run
 
# Configure with full mode, no prompts
npx crawlio-mcp init --full --yes
 
# Set up portal mode with launchd
npx crawlio-mcp init --portal

What gets installed

Install path	Pillars	Notes
Direct bundle ("Install MCP" in Settings)	Chrome Extension + Headless Agent + Crawlio App	Writes `~/.crawlio-mcp.json`
`npx @crawlio/mcp`	Headless Agent + Crawlio App	Prints Chrome Web Store URL for the extension
App Store + `npx @crawlio/mcp`	Headless Agent + Crawlio App	Chrome extension installs independently

Prerequisites

Crawlio.app installed and running (direct distribution, not App Store sandbox)
Node.js v18+ for the npx install path (optional if using Homebrew or the app bundle)

Manual configuration

If you prefer to configure manually, add the MCP server entry to your client's config file.

Recommended: npx (zero-install)

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

The npm wrapper finds the CrawlioMCP binary from the app bundle, Homebrew, or downloads it from GitHub.

Full mode (all 49 tools)

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

Homebrew binary (direct)

brew install crawlio-app/tap/crawlio-mcp

{
  "mcpServers": {
    "crawlio": {
      "command": "crawlio-mcp"
    }
  }
}

Build from source

swift build -c release --product CrawlioMCP

{
  "mcpServers": {
    "crawlio": {
      "command": "/path/to/Crawlio-app/.build/release/CrawlioMCP"
    }
  }
}

Per-client config paths

Client	Config path	Server key
Global	`~/.mcp.json`	`mcpServers`
Project	`.mcp.json`	`mcpServers`
Claude Code	`~/.claude.json`	`mcpServers`
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json`	`mcpServers`
Cursor	`~/.cursor/mcp.json`	`mcpServers`
VS Code	`~/Library/Application Support/Code/User/mcp.json`	`servers`
Windsurf	`~/.codeium/windsurf/mcp_config.json`	`mcpServers`
Zed	`~/Library/Application Support/Zed/settings.json`	`mcpServers`
Gemini CLI	`~/.gemini/settings.json`	`mcpServers`
GitHub Copilot CLI	`~/.copilot/mcp-config.json`	`mcpServers`
ChatGPT Desktop	Configured via UI	N/A

ℹ️

VS Code uses "servers" as the key, not "mcpServers". The init wizard handles this automatically.

Verify your connection

After setup, ask your AI:

"What is the Crawlio crawl status?"

If configured correctly, the AI calls get_crawl_status and returns the engine state. If Crawlio.app is running and idle, you see "engineState": "idle".

Vault setup

Store your first authenticated session:

Ask your AI: "Log me into example.com"
The AI calls vault_request_login with the login URL
Crawlio opens an auth browser window
Log in normally. Crawlio captures the session.
The session is encrypted and stored. All 3 pillars can use it for authenticated crawls.

Check stored sessions:

"What domains do I have sessions for?"

The AI calls vault_list_domains and lists your stored sessions.

Portal mode

Portal mode runs CrawlioMCP as a persistent HTTP server instead of a per-session stdio subprocess.

npx crawlio-mcp init --portal

This installs a launchd service that:

Starts on login (RunAtLoad: true)
Auto-restarts on crash (KeepAlive: true)
Listens on http://127.0.0.1:3001/mcp
Logs to ~/Library/Logs/Crawlio/mcp-server.log

Client configuration for portal mode:

{
  "mcpServers": {
    "crawlio": {
      "url": "http://127.0.0.1:3001/mcp"
    }
  }
}

Portal endpoints:

Endpoint	Description
`POST /mcp`	MCP protocol endpoint
`GET /health`	Server health check with version, uptime, tool count
`GET /setup`	HTML page with config snippet and copy button
`GET /sse`	SSE endpoint for streaming

Binary resolution chain

The npm wrapper and init wizard search for the CrawlioMCP binary in this order:

$CRAWLIO_MCP_BINARY environment variable
~/.crawlio/bin/CrawlioMCP (npm auto-download cache)
/Applications/Crawlio.app/Contents/Helpers/CrawlioMCP
~/Applications/Crawlio.app/Contents/Helpers/CrawlioMCP
/opt/homebrew/bin/crawlio-mcp (Homebrew arm64)
/usr/local/bin/crawlio-mcp (Homebrew Intel)
Auto-download from GitHub Releases

Troubleshooting

"App not running" errors

Control tools (start, stop, pause) require Crawlio.app to be running. Read-only tools fall back to file-based state. Make sure Crawlio.app is open.

Socket file missing

If ~/Library/Logs/Crawlio/control.sock does not exist, Crawlio.app has not started its control server. Try:

Quit and relaunch Crawlio.app
Check Console.app for Crawlio error logs
Verify the app is the direct-distribution version (not a sandboxed build)

Binary not found

If npx crawlio-mcp fails to find the binary:

# Check if the app bundle has the helper
ls /Applications/Crawlio.app/Contents/Helpers/CrawlioMCP
 
# Or install via Homebrew
brew install crawlio-app/tap/crawlio-mcp
 
# Or set the path explicitly
export CRAWLIO_MCP_BINARY=/path/to/CrawlioMCP

AI client shows no tools

Make sure the server entry is in the correct config file. For Claude Code, use ~/.claude.json or the project-level .mcp.json. Run claude mcp list to see registered servers.

Next steps

MCP Overview: what Crawlio MCP does and how the 3 pillars work
Code Mode: reduce schema tokens with 6 tools instead of 49
Tool Reference: all 49 Crawlio App tools with parameters
Browser Agent Setup: add Chrome automation

PreviousOverview NextCode Mode