Introduction

Getting started

Install webfetch, run your first federated image search, and wire it into your agent in under five minutes.

This page gets you from zero to a working license-safe image search in under five minutes. Pick an install path, run a sample query, and wire the MCP server into your IDE.

#Install

curl -fsSL https://raw.githubusercontent.com/ashlrai/web-fetcher-mcp/main/install/install.sh | bash

This clones the repo to ~/.webfetch/repo, installs bun if missing, builds the CLI, symlinks webfetch onto your $PATH, and (with your consent) merges the MCP entry into ~/.claude/settings.json. Re-run any time to update.

For CI and Dockerfiles, use the non-interactive variant:

curl -fsSL https://raw.githubusercontent.com/ashlrai/web-fetcher-mcp/main/install/install.sh | bash -s -- --yes --no-claude

#Option B — npm

npm install -g @webfetch/cli

#Option C — Homebrew (macOS / Linux)

brew install ashlrai/tap/webfetch

#Option D — Docker

docker pull ghcr.io/ashlrai/webfetch:latest
docker run --rm ghcr.io/ashlrai/webfetch:latest search "drake portrait" --limit 3
webfetch search "drake portrait" --limit 3

Expected output: a table of three candidates with license tags and confidence scores. Exit code 0. Every row shows the provider, license tag, confidence, resolution, and source URL.

#  PROVIDER         LICENSE       CONF   DIMS        URL
1  wikimedia        CC_BY_SA      0.95   2048x1365   https://upload.wikimedia.org/...
2  openverse        CC_BY         0.95   1600x1067   https://live.staticflickr.com/...
3  spotify          EDITORIAL     0.90   1000x1000   https://i.scdn.co/image/...

#Result anatomy

Every candidate is a JSON object with these fields:

  • url — canonical image URL (direct, not a search page).
  • thumbnailUrl — smaller variant if the provider exposes one.
  • sourcePageUrl — human-viewable page the image lives on.
  • license — one of CC0 | PUBLIC_DOMAIN | CC_BY | CC_BY_SA | EDITORIAL_LICENSED | PRESS_KIT_ALLOWLIST | UNKNOWN.
  • licenseUrl — permalink to the license text (when available).
  • confidence — 0–1; see License safety for the rubric.
  • author, authorUrl — photographer or creator, if known.
  • attributionLine — pre-formatted single-line credit string ready to render.
  • provider, providerNative — which source surfaced it.
  • width, height, mime — pixel dimensions and MIME type when available.
  • sha256, byteSize — filled in after webfetch download.

Run with --json to get the raw array, --verbose to see provider-level timing and warnings on stderr.

#Install the MCP for Claude Code

The installer above does this automatically. If you declined, or want to do it manually:

claude mcp add webfetch -- npx -y @webfetch/mcp

Restart Claude Code. In a new chat, ask it to "list the providers available in webfetch". It should return a JSON list with ~20 providers.

Per-IDE instructions: Claude Code · Cursor · Cline · Continue · Roo Code · Codex.

#Sign up for webfetch Cloud (optional)

Self-hosting is fully supported and always will be. webfetch Cloud is a hosted version that adds pooled provider keys (so you don't have to manage 8 different API tokens), a shared cache, usage dashboards, and a Bright Data / Camoufox browser pool for the fallback layer. It's the fastest way to production.

Sign up at app.getwebfetch.com/signup — first 1000 fetches per month are free.

#What's next