webfetch is positioned as a "license-first image layer for AI agents and humans." Its core goal is to solve four types of problems when manually obtaining images: unclear licenses making safe publication impossible, difficulty scripting it, the Google Images search API being discontinued with scraping being fragile and in a gray area of the terms of service, and the lack of a shared cache leading to repeated downloads.
Purpose
webfetch is used to search, filter, and download images within AI agents or automated workflows, while ensuring that every returned image has traceable license information. It federates 25 image providers, sorts by license priority, and by default rejects UNKNOWN results whose license cannot be determined.
Main capabilities
- Federated search: aggregates results across 25 image providers, all of which are direct-source APIs with stable terms and structured license metadata.
- License-first sorting: the sorting basis is, in order, license label, metadata confidence, resolution, provider priority; UNKNOWN is rejected by default (under the Berne Convention, most web content is all rights reserved unless proven otherwise).
- Result fields: returns license label, attribution string, dimensions, and download URL.
- Multiple access methods: one MCP server, one CLI, one HTTP server; any agent that supports MCP (Claude Code, Cursor, Cline, Continue, Roo Code, Codex) can connect with a one-line configuration.
- Companion tools: Chrome extension, Python SDK, TypeScript SDK.
- Shared cache: all interfaces share ~/.webfetch/cache/, keyed by SHA-256, and files downloaded by the CLI can be used immediately by the MCP server, and vice versa.
- Daemon mode: webfetch watch supports repeated queries or incremental refreshes.
- Bring-your-own provider plugin API.
- Hosted layer: getwebfetch.com provides pooled provider keys, managed browser fallback, and a team usage dashboard.
Usage
30-second usage example:
- MCP: call directly within any agent that supports MCP.
- Call via the TypeScript library. For installation, the curl | bash installer idempotently connects webfetch to Claude Code's ~/.claude/settings.json, and can be rerun at any time to update. For package-level API documentation, see packages/core/README.md, packages/browser/README.md, and the other READMEs under packages/. Local and cloud modes: the CLI is local-first, and by default webfetch search, artist, album, download, probe, license, and batch call webfetch-core in-process and use the provider API keys from environment variables. Passing --cloud or setting WEBFETCH_MODE=cloud calls https://api.getwebfetch.com/v1/*，需使用 WEBFETCH_API_KEY or webfetch config set apiKey wf_live_.... Local mode is suitable for directly calling providers and local caching; cloud mode is suitable for managed authentication, pooled provider keys, managed browser fallback, usage statistics, or team governance.
Use cases
Suitable for automated pipelines that need to safely publish images without manual review, especially scenarios where AI agents need to obtain images in license-compliant ways. Also suitable for teams that need batch, scriptable image retrieval while retaining attribution information.
Limits and default policy
Secure defaults: licensePolicy is "safe-only" (allows open, platform-licensed, editorial/press-release categories, rejects UNKNOWN); safeSearch is "strict"; opt-in providers (youtube-thumb, bing, serpapi, browser, managed-browser, europeana-archival) are disabled by default; single download limit is 20MB; content-type guard; host blacklist; follows robots.txt for generic page probing. License migration note: older builds treated Unsplash, Pexels, and Pixabay as CC0, while the current build explicitly exposes their platform terms. Most callers should keep licensePolicy: "safe-only", because it still allows open, platform, editorial, and press-release categories while rejecting UNKNOWN; pipelines that only need Creative Commons or public domain material should use licensePolicy: "open-only" and update type guards to handle these three platform labels separately. Regarding pricing and specific fee information, the material only mentions that the hosted tier is located at getwebfetch.com and includes pricing information, but does not provide specific pricing content.
Development and contributions
Issues and PRs are welcome. You can start by running bun install && bun test, and refer to the domain-specific reference documents under docs/.
