crawlio-mcp

MCP server for Crawlio — the AI-native macOS website crawler.

Exposes 36 tools and 4 resources over stdio transport, compatible with any MCP client (Claude Code, Cursor, Windsurf, VS Code, Zed, etc.).

Install

Zero-install (recommended)

npx crawlio-mcp init

Downloads the binary automatically and configures all detected MCP clients.

Homebrew

brew install crawlio-app/tap/crawlio-mcp
crawlio-mcp init

Bundled with Crawlio.app

brew install --cask crawlio-app/tap/crawlio

The desktop app bundles the MCP server — the cask symlinks it to your PATH automatically.

Quick Setup

Run init to auto-detect and configure your AI clients:

npx crawlio-mcp init          # Configure all detected clients
npx crawlio-mcp init --full   # Enable all 36 tools (default: 6 code-mode tools)
npx crawlio-mcp init --portal # HTTP transport + launchd auto-start
npx crawlio-mcp init --dry-run # Preview changes without writing

Manual configuration

Add to your MCP client config (.mcp.json, mcp.json, etc.):

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

Prerequisites

• macOS 15 (Sequoia) or later
• Crawlio.app must be running for control tools (read-only tools work offline)

How it works

This npm package is a thin wrapper that locates or downloads the native CrawlioMCP binary and forwards stdio through it. Binary resolution order:

1. $CRAWLIO_MCP_BINARY environment variable
2. ~/.crawlio/bin/CrawlioMCP (npm auto-download cache)
3. /Applications/Crawlio.app/Contents/Helpers/CrawlioMCP
4. ~/Applications/Crawlio.app/Contents/Helpers/CrawlioMCP
5. /opt/homebrew/bin/crawlio-mcp (Homebrew)
6. /usr/local/bin/crawlio-mcp

If no binary is found, it downloads from GitHub Releases on first run.

Tools

36 tools across 8 categories:

| Category | Count | Tools | |----------|-------|-------| | Status & Monitoring | 6 | get_crawl_status, get_crawl_logs, get_errors, get_downloads, get_failed_urls, get_site_tree | | Control | 4 | start_crawl, stop_crawl, pause_crawl, resume_crawl | | Settings & Config | 3 | get_settings, update_settings, recrawl_urls | | Projects | 5 | list_projects, save_project, load_project, delete_project, get_project | | Export & Extraction | 5 | export_site, get_export_status, extract_site, get_extraction_status, trigger_capture | | Composite Analysis | 2 | analyze_page (capture + poll + status in one call), compare_pages (two-site comparison with summary) | | Enrichment | 6 | get_enrichment, submit_enrichment_bundle, submit_enrichment_framework, submit_enrichment_network, submit_enrichment_console, submit_enrichment_dom | | Observations & Findings | 4 | get_observations, create_finding, get_findings, get_crawled_urls | | OCR | 1 | extract_text_from_image |

Plus 3 HTTP-only endpoints accessible via execute_api: get_health, get_debug_metrics, dump_state.

Resources

| URI | Description | |-----|-------------| | crawlio://status | Engine state and progress | | crawlio://settings | Current crawl settings | | crawlio://site-tree | Downloaded file tree | | crawlio://enrichment | Browser enrichment data |

Links

• Integration guides
• MCP tools reference
• Crawlio website