Web Crawler MCP

Web Crawler MCP

A powerful web crawling tool that integrates with AI assistants via the MCP (Model Context Protocol). This project allows AI assistants to crawl websites, extract dynamic content, navigate through links, and save structured Markdown files directly.

📋 Features

• Native integration with AI assistants via MCP
• Return scraped Markdown content directly to the AI
• Extracts and surfaces internal/external links for AI navigation
• Website crawling with configurable depth and page limit
• Detailed crawl result statistics, including the list of skipped pages
• Live progress notifications during long crawls
• Saved results exposed as MCP resources (crawl://results/...)
• Error and not found page handling
• Secure by default: only public http(s) URLs, JavaScript disabled unless you opt in
• Advanced Scraping Capabilities:
  • Magic Mode: crawl4ai heuristics that simulate a real browser and help with some anti-bot protections (not a guaranteed bypass)
  • Targeted Extraction: Fetch only what you need using CSS selectors
  • Custom JavaScript (opt-in): Execute code before extraction (clicks, scrolls, form fills)
  • Persistent Sessions: One browser is shared across calls, so a session_id keeps cookies and state until it is closed (close_session) or stays idle too long
  • SPA Support: Wait for dynamic CSS selectors or set explicit pre-extraction delays

🚀 MCP Configuration

The simplest and recommended way to use this tool is via uvx. The @latest suffix makes uvx check PyPI at each start and run the newest published version (without it, uvx keeps reusing the version it cached the first time).

Prerequisites

• uv installed on your system.

Setup for AI Assistants (e.g., Claude Desktop, Cline)

Add the following to your AI Assistant's MCP configuration file (e.g., cline_mcp_settings.json or claude_desktop_config.json):

Note: Python 3.12 or 3.13 is required (crawl4ai does not support 3.14 yet). Specifying --python 3.13 is recommended, especially on Windows, to avoid compilation issues with certain dependencies.

From PyPI (recommended):

{
  "mcpServers": {
    "crawl": {
      "command": "uvx",
      "args": [
        "--python",
        "3.13",
        "crawl4ai-mcp-llm@latest"
      ],
      "disabled": false,
      "autoApprove": [],
      "timeout": 600
    }
  }
}

From GitHub (latest unreleased):

{
  "mcpServers": {
    "crawl": {
      "command": "uvx",
      "args": [
        "--python",
        "3.13",
        "--from",
        "git+https://github.com/laurentvv/crawl4ai-mcp-llm",
        "crawl4ai-mcp-llm"
      ],
      "disabled": false,
      "autoApprove": [],
      "timeout": 600
    }
  }
}

Claude Code:

claude mcp add crawl -s user -- uvx --python 3.13 crawl4ai-mcp-llm@latest

Important: Browser Installation

The crawler uses Playwright to handle dynamic content. Install Chromium once after setting up the tool:

# When running the server with uvx (recommended setup)
uvx --python 3.13 --from crawl4ai-mcp-llm@latest playwright install chromium

# From a local clone
uv run playwright install chromium

🖥️ Usage

Once configured, you can use the crawler by asking your AI assistant to perform a crawl.

Usage Examples with Claude/Cline

• Single Page: "Fetch https://docs.python.org/3/library/re.html (just that page) and summarize it."
• Simple Crawl: "Can you crawl the site example.com and give me a summary?"
• Crawl with Options: "Can you crawl https://example.com with a depth of 3 and include external links?"
• Dynamic Content: "Crawl this React app and wait for the .main-content selector to load."
• Anti-bot Heuristics: "Crawl example.com with magic mode enabled."
• Targeted Extraction: "Crawl the docs site but only extract content matching the h1, p.lead CSS selector."

🧰 Tools and Resources

The crawl response includes the resource URI of its result: when the returned content is truncated, the assistant can read the complete file through that resource even if it has no access to the server's file system.

Progress: crawl sends an MCP progress notification after each page. Clients that reset their timeout on progress can use a shorter timeout; otherwise keep a generous one (e.g. 600 s).

🛠️ Available Parameters (crawl tool)

The crawl tool accepts the following parameters (crawl_page accepts url, css_selector, wait_for_selector, magic, session_id, delay_before_return_html and max_content_chars):

⚙️ Configuration (environment variables)

Set these in the env section of your MCP configuration:

🔒 Security

The AI assistant decides which URLs are crawled, and crawled pages may contain prompt-injection attempts. The server therefore:

• only accepts http/https URLs (no file://, raw:, data: ...), and rejects hosts resolving to loopback, private or link-local addresses unless CRAWL4AI_MCP_ALLOW_PRIVATE_NETWORKS=true;
• runs no custom JavaScript (including js: wait conditions) unless CRAWL4AI_MCP_ALLOW_JS=true;
• writes files only inside the results directory and never overwrites them without overwrite=true;
• wraps returned page content in <untrusted-web-content> tags so the assistant treats it as data.

Redirects and links discovered during a deep crawl are filtered on their URL only (no DNS lookup): keep private-network access disabled when the server can reach sensitive internal services.

👨‍💻 Development

If you want to modify the crawler or run it locally:

1. Clone this repository:

git clone https://github.com/laurentvv/crawl4ai-mcp-llm
cd crawl4ai-mcp-llm

2. Install dependencies using uv:

uv sync

3. Test the MCP server locally using the official MCP Inspector:

npx -y @modelcontextprotocol/inspector uv run crawl4ai-mcp-llm

4. Run the checks (unit tests never hit the network):

uv run pytest --cov                # unit tests + coverage report (80% minimum)
uv run pytest -m integration       # real crawls, needs network and Chromium
uv run ruff check . && uv run ruff format --check . && uv run mypy

5. Run the MCP server directly (for standard usage):

uv run crawl4ai-mcp-llm

Changes are listed in CHANGELOG.md.

🤝 Contribution

Contributions are welcome! Feel free to open an issue or submit a pull request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.