unclecode/crawl4ai installation guide

Install Crawl4AI on macOS Tahoe (Apple silicon)

What you are installing

Crawl4AI is an Apache-2.0-licensed web crawler and scraper written primarily in Python. It can turn web pages into LLM-friendly Markdown, extract HTML, take screenshots, create PDFs, execute JavaScript in a browser, and crawl multiple URLs.

For a Mac with Apple silicon, this guide uses the project’s **prebuilt Docker image**. The repository calls this its recommended Docker option, and its first-party files say the image has a multi-architecture manifest supporting `linux/arm64`. Docker should therefore select the ARM64 image appropriate for an Apple-silicon Mac automatically.

This route also provides the repository’s documented Model Context Protocol (MCP) connection for Claude Code. You do not need to clone the GitHub repository or build Crawl4AI yourself.

How this relates to Claude Code

**Classification:** runs alongside Claude Code.

**Mechanisms:** tool surface, external CLI/library, and local infrastructure.

Crawl4AI is not evidenced as a native Claude Code plugin, hook, or Agent Skill. Instead, it runs as a separate local Docker server. That server exposes an MCP endpoint, and Claude Code can register that endpoint as a provider. Once connected, the documented MCP tools include Markdown generation, HTML extraction, screenshots, PDF creation, JavaScript execution, multi-URL crawling, and access to Crawl4AI library context.

Before you begin

The repository documents these Docker prerequisites:

• Docker 20.10.0 or newer, installed and running.
• Docker Compose, normally bundled with Docker Desktop.
• At least 4 GB of RAM available to the container; more is recommended for heavy use.
• Git only if cloning the source, which this installation path does not require.
• Python 3.10+ only if using the separate Python SDK, which is not required here.
• Claude Code if you intend to make the optional MCP connection.

The supplied repository files do not document a command for installing Docker Desktop or Claude Code. Install those applications from their official first-party distribution channels, then open Docker Desktop and wait until it reports that Docker is running. This guide does not invent an installation command for either prerequisite.

The repository explicitly documents ARM64 Docker images, but it does not provide a macOS Tahoe compatibility statement. This guide therefore relies on Docker’s documented ARM64 route rather than claiming separate native Tahoe certification.

Step 1: Open Terminal

Open **Terminal** on your Mac. You can find it with Spotlight or under **Applications → Utilities**.

Commands in this guide are intended to be pasted into Terminal one block at a time. Lines beginning with `#` are comments supplied in the repository examples; the shell ignores them.

Step 2: Check that Docker is available

With Docker Desktop running, paste:

docker info

The repository recommends this command to check the Docker installation and available resources. A normal Docker information report means the Docker engine is reachable. If Terminal reports that it cannot connect to Docker, return to Docker Desktop and make sure it has finished starting. If it says `docker` is not found, Docker has not been installed or is not available to your shell yet.

Step 3: Download the Crawl4AI image

Pull the repository’s latest image:

# Or use the latest tag
docker pull unclecode/crawl4ai:latest

Docker downloads the image from Docker Hub. The first-party Docker guide says the image supports both AMD64 and ARM64 through one tag, so Docker automatically selects the platform. On Apple silicon, that should be the `linux/arm64` variant.

The download can be substantial and may take time. Leave Terminal open until the pull completes.

Step 4: Start the local Crawl4AI server

Paste the documented basic run command:

# Pull and run the latest release
docker run -d -p 11235:11235 --name crawl4ai --shm-size=1g unclecode/crawl4ai:latest

What the options mean:

• `-d` starts the container in the background.
• `-p 11235:11235` makes the service available through port 11235 on your Mac.
• `--name crawl4ai` gives the container an easy-to-recognize name.
• `--shm-size=1g` assigns shared memory used by the browser workload.
• `unclecode/crawl4ai:latest` selects the image you downloaded.

This basic setup does not add LLM-provider API keys. Ordinary crawling and the MCP server do not require you to create the optional `.llm.env` file. Provider-backed LLM extraction may require credentials, but that is a separate optional configuration.

Step 5: Verify the server

Run the documented health check:

curl http://localhost:11235/health

A response from the health endpoint confirms that something is listening at the documented Crawl4AI address. If the command cannot connect, first confirm Docker Desktop is still running. Also make sure you did not already have another container or application using port 11235 when you started Crawl4AI.

You can now use a web browser to visit these documented local pages:

• Monitoring dashboard: `http://localhost:11235/dashboard`
• Interactive playground: `http://localhost:11235/playground`

The playground is the easiest visual starting point. It lets you configure and test crawling operations and generate request data. Remember that crawling sends requests to external websites; use it only where you have permission and follow the target site’s rules and applicable law.

Step 6: Optionally connect Crawl4AI to Claude Code

Keep the Docker container running. In Terminal, register the server’s documented Server-Sent Events MCP endpoint:

# Add the Crawl4AI server as an MCP provider
claude mcp add --transport sse c4ai-sse http://localhost:11235/mcp/sse

Then ask Claude Code to list its MCP providers:

# List all MCP providers to verify it was added
claude mcp list

Look for `c4ai-sse` in the output. This registration points Claude Code to the local server at `http://localhost:11235/mcp/sse`; it does not install Crawl4AI inside Claude Code.

The repository documents these MCP tools:

• `md` for generating Markdown from web content.
• `html` for extracting preprocessed HTML.
• `screenshot` for capturing webpage screenshots.
• `pdf` for generating PDF documents.
• `execute_js` for running JavaScript on web pages.
• `crawl` for multi-URL crawling.
• `ask` for querying Crawl4AI’s library context.

The tool schemas are available in a browser at `http://localhost:11235/mcp/schema`.

If `claude mcp list` cannot reach the provider, repeat the health check. Claude Code can only use this integration while Docker Desktop and the `crawl4ai` container are running.

Optional LLM configuration

Crawl4AI can use external LLM providers, but the basic install above does not need them. The Docker guide documents an optional `.llm.env` file containing provider API keys and a different `docker run` command using `--env-file .llm.env`.

Do not copy placeholder values such as `sk-your-key` and mistake them for working credentials. API keys are secrets, may enable paid usage, and are sent to their corresponding third-party providers when those features are used. The repository warns never to commit `.llm.env` to version control. For a first installation, it is simpler and safer to leave this optional feature unconfigured until you specifically need LLM-based extraction.

Stopping and removing Crawl4AI

When you no longer want the local server running, paste the documented cleanup command:

docker stop crawl4ai && docker rm crawl4ai

This stops and removes the named container. It does not remove the downloaded Docker image, and it does not remove the MCP registration from Claude Code. The supplied first-party files do not document a Claude Code MCP removal command, so this guide does not invent one.

To use Crawl4AI again after removing the container, run the Step 4 `docker run` command again. You normally do not need to pull the image again unless you want Docker to retrieve a newer `latest` image.

Security and practical cautions

The README identifies version 0.9.3 as a security release fixing arbitrary file write, SSRF, denial-of-service, and XSS issues, and it tells users to upgrade with the latest package. Using the `latest` Docker tag follows the repository’s documented latest-image route, but a floating tag can change over time.

Treat crawled pages as untrusted content. Screenshots, PDFs, cookies, persistent browser profiles, JavaScript execution, and authenticated sessions can expose sensitive information or perform consequential actions. Do not give an agent access to logged-in pages unless that access is necessary and understood. Avoid exposing port 11235 beyond your Mac without reviewing the project’s authentication, trusted-host, rate-limit, and production-security configuration.

At this point, Crawl4AI is installed as a local ARM64-capable Docker service, its health endpoint is verified, and—if you completed Step 6—it is available to Claude Code through the documented MCP tool surface.