webfetch

A camada de imagem license-first para agentes de IA e humanos. 24 provedores federados · CC0/CC-BY/PD-first · MCP nativo · Extensão do Chrome · SDKs em Python + TS.

GitHub

Experimente este MCPPatrocinado

Documentação

webfetch

A camada de imagens com prioridade de licença para agentes de IA e humanos.

Um servidor MCP, um CLI e um servidor HTTP que federam entre 25 provedores de imagens, classificam resultados com prioridade de licença e rejeitam resultados UNKNOWN por padrão. Qualquer agente que fale MCP (Claude Code, Cursor, Cline, Continue, Roo Code, Codex) se conecta a partir de uma única linha de configuração. Página inicial, preços e uso hospedado estão em getwebfetch.com.

Instalação

Superfície	Comando único
npm	`npm i -g getwebfetch`
Homebrew	`brew tap ashlrai/webfetch && brew install webfetch`
Docker	`docker run --rm ghcr.io/ashlrai/webfetch cli help`
curl \| bash	`curl -fsSL https://raw.githubusercontent.com/ashlrai/webfetch/main/install/install.sh \| bash`

O instalador curl | bash também conecta o webfetch ao ~/.claude/settings.json do Claude Code de forma idempotente. Execute novamente a qualquer momento para atualizar.

Superfícies

Superfície	Melhor para	Ponto de entrada
CLI	scripts, trabalho em shell, transferência para agentes	`webfetch search ...`
Servidor MCP	Claude Code, Cursor, Cline, Continue, Roo Code, Codex	`npx -y getwebfetch-mcp`
Servidor HTTP	integrações e extensões locais	`npx -y webfetch-server`
Biblioteca principal	aplicativos TypeScript e ferramentas personalizadas	`npm i webfetch-core`
Camada de navegador	extração de fallback e fluxos com navegador gerenciado	`npm i webfetch-browser`
Nuvem hospedada	chaves agrupadas, rastreamento de uso, controles de equipe	app.getwebfetch.com

As notas de API por pacote estão em packages/core/README.md, packages/browser/README.md e nos demais READMEs de pacotes em packages/.

Uso em 30 segundos

CLI:

webfetch search "drake portrait" --limit 5
webfetch artist "Taylor Swift" --kind portrait --min-width 1200
webfetch download <url> --out ./portrait.jpg
printf "drake portrait\nradiohead album\n" | webfetch batch --jsonl --continue-on-error

MCP (de dentro de qualquer agente que fale MCP):

search_images({ query: "drake portrait", limit: 5 })
search_artist_images({ artist: "Taylor Swift", kind: "portrait" })
download_image({ url: "..." })

Biblioteca TypeScript:

import { searchArtistImages, pickBest, downloadImage } from "webfetch-core";

const { candidates } = await searchArtistImages("Drake", "portrait");
const best = pickBest(candidates, { minWidth: 1200 });
if (best) {
  const { cachedPath, sha256 } = await downloadImage(best.url);
  console.log(best.attributionLine, "->", cachedPath);
}

Qual problema isso resolve

Obter uma imagem manualmente tem quatro modos de falha:

Você não conhece a licença, então não pode publicar o resultado com segurança.
Você não consegue automatizar — cada novo site significa mais uma tarde de trabalho.
A API de Pesquisa de Imagens do Google foi descontinuada; scraping é frágil e viola os termos de uso.
Sem cache compartilhado — você baixa o mesmo arquivo dezenas de vezes.

O webfetch resolve todos os quatro federando APIs de fontes diretas que possuem termos estáveis e metadados de licença estruturados, classificando candidatos com prioridade de licença e expondo o resultado como uma única ferramenta MCP.

Provedores

Provedor	Cobre	Licença padrão	Autenticação	Opt-in
wikimedia	retratos, eventos, logotipos, história	CC_BY_SA (metadados)	—	não
openverse	qualquer conteúdo licenciado CC	CC_BY (metadados)	—	não
unsplash	fotografia de alta qualidade	`UNSPLASH_LICENSE`	`UNSPLASH_ACCESS_KEY`	não
pexels	fotografia de banco de imagens	`PEXELS_LICENSE`	`PEXELS_API_KEY`	não
pixabay	fotos de banco + ilustrações	`PIXABAY_LICENSE`	`PIXABAY_API_KEY`	não
itunes	capas de álbuns, retratos de artistas	EDITORIAL_LICENSED	—	não
musicbrainz-caa	arte de álbum canônica	EDITORIAL_LICENSED	—	não
spotify	imagens de artistas + álbuns	EDITORIAL_LICENSED	`SPOTIFY_CLIENT_ID/SECRET`	não
youtube-thumb	miniaturas de vídeos	EDITORIAL_LICENSED	—	sim
brave	pesquisa geral de imagens na web	UNKNOWN (+heurística)	`BRAVE_API_KEY`	não
bing	pesquisa geral de imagens na web	UNKNOWN (+heurística)	`BING_API_KEY`	sim
serpapi	Google Images + busca reversa	UNKNOWN (+heurística)	`SERPAPI_KEY`	sim
browser	fallback headless vs images.google.com	UNKNOWN	—	sim
managed-browser	fallback de navegador gerenciado Bright Data	UNKNOWN	`BRIGHTDATA_API_TOKEN`	sim
flickr	fotografia CC / domínio público	CC_BY (metadados)	`FLICKR_API_KEY`	não
internet-archive	mídia de arquivo de domínio público / CC	PUBLIC_DOMAIN	—	não
smithsonian	mídia de museu em Open Access	CC0	`SMITHSONIAN_API_KEY`	não
nasa	imagens da NASA	PUBLIC_DOMAIN	—	não
met-museum	The Met Open Access	CC0	—	não
europeana	patrimônio cultural europeu	CC_BY (metadados)	`EUROPEANA_API_KEY`	não
library-of-congress	arquivo histórico dos EUA	PUBLIC_DOMAIN	—	não
wellcome-collection	imagens médicas/históricas	CC_BY (metadados)	—	não
rawpixel	fatia de banco de imagens CC0	CC0	`RAWPIXEL_API_KEY` opcional	não
burst	fotos de banco do Shopify Burst	CC0	—	não
europeana-archival	registros de texto/manuscritos da Europeana	CC_BY (metadados)	`EUROPEANA_API_KEY`	sim

Consulte docs/PROVIDERS.md para armadilhas, limites de taxa e docs/PROVIDER_TUNING.md para escolhas por caso de uso.

Modos local e nuvem

O CLI é local-first: por padrão, webfetch search, artist, album, download, probe, license e batch chamam webfetch-core em processo e usam chaves de API dos provedores do seu ambiente. Passe --cloud ou defina WEBFETCH_MODE=cloud para chamar https://api.getwebfetch.com/v1/* com WEBFETCH_API_KEY ou webfetch config set apiKey wf_live_....

Use o modo local quando quiser chamadas diretas aos provedores e um cache local. Use o modo nuvem quando quiser autenticação hospedada, chaves de provedores agrupadas, fallback de navegador gerenciado, contabilidade de uso ou controles de equipe.

Por que prioridade de licença

O único resultado que rejeitamos por padrão é uma imagem que não conseguimos justificar. Uma foto marginalmente melhor sob licença desconhecida é inútil para um pipeline que precisa publicar sem revisão humana. Empates de relevância são fáceis de desfazer; procedência não é.

O classificador ordena por: tag de licença -> confiança dos metadados -> resolução -> prioridade do provedor. UNKNOWN é rejeitado por padrão (Convenção de Berna: a maior parte da web é todos-os-direitos-reservados, salvo prova em contrário). Consulte docs/LICENSE_POLICY.md.

Migração: provedores de banco de imagens CC0

Versões antigas do webfetch tratavam Unsplash, Pexels e Pixabay como CC0. As versões atuais expõem os termos das plataformas explicitamente:

Tag antiga	Tag nova	O que verificar
`CC0` do Unsplash	`UNSPLASH_LICENSE`	Termos do Unsplash; não é Creative Commons
`CC0` do Pexels	`PEXELS_LICENSE`	Termos do Pexels; não é Creative Commons
`CC0` do Pixabay	`PIXABAY_LICENSE`	Termos do Pixabay; não é Creative Commons

A maioria dos chamadores deve manter licensePolicy: "safe-only" porque ainda permite categorias abertas, de plataforma, editoriais e de press kit, rejeitando UNKNOWN. Pipelines que exigem apenas ativos Creative Commons ou de domínio público devem usar licensePolicy: "open-only" e atualizar os guards de tipo para tratar as três tags de plataforma separadamente.

webfetch vs alternativas

Capacidade	webfetch	Google Images bruto	Somente Unsplash	Bing CSE
Automatizável via API	sim	não (descontinuado)	sim	sim
Metadados de licença por resultado	sim	não	sim (uma licença)	parcial
Cobre arte musical editorial	sim	parcial	não	parcial
Cobre CC / domínio público	sim	não	não	não
Seguro por padrão (rejeita UNKNOWN)	sim	n/d	n/d	não
Cache compartilhado por conteúdo	sim	não	não	não
Linha de atribuição pré-construída	sim	não	não	não
Uma linha de configuração MCP em todas as IDEs	sim	não	não	não
Sem custo por consulta nos padrões	sim	n/d	sim	não

Arquitetura

                             +------------------+
                             |  webfetch-core  |
                             |  (ranker, cache, |
                             |   license coerce)|
                             +---------+--------+
                                       |
          +----------------+-----------+-----------+----------------+
          |                |                       |                |
  +-------v------+  +------v-------+       +-------v------+  +------v-------+
  | webfetch     |  | webfetch-mcp |       | webfetch-    |  | browser      |
  | CLI          |  | (stdio)      |       | server (HTTP)|  | extensions   |
  +-------+------+  +------+-------+       +-------+------+  +------+-------+
          |                |                       |                |
          |                |                       |                |
          +----------------+-----------+-----------+----------------+
                                       |
                 +---------------------v---------------------+
                 |              provider adapters            |
                 |  wikimedia  openverse  unsplash  pexels    |
                 |  pixabay    itunes     mb-caa    spotify   |
                 |  youtube    brave      bing      serpapi   |
                 |  flickr     nasa       met       europeana |
                 |  loc        wellcome   rawpixel  burst     |
                 |  browser + managed-browser + archival opt-in|
                 +-------------------------------------------+

Toda superfície compartilha ~/.webfetch/cache/ indexado por SHA-256, então um download do CLI fica instantaneamente disponível para o servidor MCP e vice-versa.

Padrões de segurança

licensePolicy: "safe-only" — categorias abertas, de licença de plataforma e editoriais/press kit são permitidas; UNKNOWN é rejeitado.
safeSearch: "strict".
Provedores opt-in (youtube-thumb, bing, serpapi, browser, managed-browser, europeana-archival) desativados por padrão.
Limite de 20 MB por download, guard de tipo de conteúdo, lista de bloqueio de hosts.
robots.txt respeitado em sondagens genéricas de páginas.

Roadmap

webfetch watch — modo daemon para consultas repetidas / atualização incremental.
API de plugin traga-seu-próprio-provedor.
Nível hospedado em getwebfetch.com — chaves de provedores agrupadas, fallback de navegador gerenciado, painel de uso da equipe.

Contribuindo

Issues e PRs são bem-vindos. Execute bun install && bun test para começar. Consulte docs/ para documentação de referência por área.

Licença

MIT.