webfetch

👁 npm version
👁 CI
👁 License: MIT
👁 Discord
👁 GitHub stars

面向 AI 智能体和人类的“许可优先”图像层。

一个 MCP 服务器、一个 CLI 和一个 HTTP 服务器，可联合 25 个图像提供商，按许可优先对结果进行排名，并默认拒绝 UNKNOWN（未知）结果。任何支持 MCP 的智能体（Claude Code、Cursor、Cline、Continue、Roo Code、Codex）只需一行配置即可连接。着陆页、定价和托管服务请访问 getwebfetch.com。

安装

curl | bash 安装程序还会幂等地将 webfetch 写入 Claude Code 的 ~/.claude/settings.json 中。随时重新运行即可更新。

Related MCP server: Wikimedia-Search-Images

30 秒上手

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（在任何支持 MCP 的智能体内部使用）:

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

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);
}

解决的问题

手动获取图像有四种失败模式：

1. 你不知道许可协议，因此无法安全地发布结果。

2. 无法脚本化 —— 每增加一个新网站都需要耗费一下午时间。

3. Google 图像搜索 API 已停用；爬虫技术脆弱且处于服务条款的灰色地带。

4. 没有共享缓存 —— 你会重复下载同一个文件数十次。

webfetch 通过联合具有稳定条款和结构化许可元数据的直接来源 API，按许可优先对候选结果进行排名，并将结果作为单个 MCP 工具公开，从而解决了上述所有四个问题。

提供商

请参阅 docs/PROVIDERS.md 了解注意事项和速率限制，参阅 docs/PROVIDER_TUNING.md 了解针对不同用例的选择。

本地和云端模式

CLI 优先采用本地模式：默认情况下 webfetch search、artist、album、download、probe、license 和 batch 会在进程内调用 webfetch-core 并使用你环境中的提供商 API 密钥。传递 --cloud 或设置 WEBFETCH_MODE=cloud 即可使用 WEBFETCH_API_KEY 或 webfetch config set apiKey wf_live_... 调用 https://api.getwebfetch.com/v1/*。

当你需要直接调用提供商并使用本地缓存时，请使用本地模式。当你需要托管认证、共享提供商密钥池、托管浏览器回退、使用统计或团队控制时，请使用云端模式。

为什么选择“许可优先”

我们默认拒绝的唯一结果是无法证明其合法性的图像。对于需要无需人工审核即可发布的工作流而言，一张许可不明但质量稍好的照片毫无价值。相关性很容易判断，但来源证明则不然。

排序逻辑为：许可标签 -> 元数据置信度 -> 分辨率 -> 提供商优先级。UNKNOWN 默认被拒绝（根据伯尔尼公约：除非另有证明，否则大多数网络内容均为版权所有）。请参阅 docs/LICENSE_POLICY.md。

迁移：CC0 图库提供商

旧版 webfetch 将 Unsplash、Pexels 和 Pixabay 视为 CC0。当前版本明确公开了它们的平台条款：

大多数调用者应保持 licensePolicy: "safe-only"，因为它仍然允许开放、平台许可、编辑和新闻稿类别，同时拒绝 UNKNOWN。仅需要知识共享或公有领域资产的工作流应使用 licensePolicy: "open-only" 并更新类型守卫以分别处理这三个平台标签。

webfetch 与替代方案对比

架构

 +------------------+
 | 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|
 +-------------------------------------------+

所有界面共享 ~/.webfetch/cache/，并以 SHA-256 为键，因此从 CLI 下载的内容可立即供 MCP 服务器使用，反之亦然。

安全默认设置

• licensePolicy: "safe-only" — 允许开放、平台许可和编辑/新闻类别；拒绝 UNKNOWN。

• safeSearch: "strict"。

• 可选提供商（youtube-thumb、bing、serpapi、browser、managed-browser、europeana-archival）默认关闭。

• 每次下载上限 20 MB，内容类型守卫，主机黑名单。

• 在通用页面探测时遵守 robots.txt。

路线图

• webfetch watch — 用于重复查询/增量刷新的守护进程模式。

• 自带提供商插件 API。

• getwebfetch.com 托管层 — 提供商密钥池、托管浏览器回退、团队使用仪表板。

贡献

欢迎提交 Issue 和 PR。运行 bun install && bun test 即可开始。请参阅 docs/ 获取各领域的参考文档。

许可

MIT。

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?Related Servers

Tools

• download_imageA
• fetch_with_licenseA
• find_similarA
• probe_pageA
• search_album_coverA
• search_artist_imagesA
• search_imagesA