webfetch

webfetch MCP

为任何支持 MCP 的 Agent 提供以许可证为先的图片搜索与下载。

每条结果都包含结构化的许可证标签（CC0、CC_BY、CC_BY_SA、平台许可证标签、EDITORIAL_LICENSED 等）、置信度分数，以及可直接渲染的署名信息。覆盖 25 个提供商，其中 19 个为默认启用——Wikimedia Commons、Openverse、iTunes、MusicBrainz CAA、NASA、The Met、Library of Congress、Internet Archive、Wellcome Collection 和 Burst 均无需 API 密钥。

---

为什么选择 webfetch MCP？

大多数图片搜索工具只提供 URL。webfetch 除了提供 URL，还会提供必要的法律元数据，以便将图片归类为可开放／商用复用、平台许可证、仅限编辑用途或仅供探索。MCP 层提供七个可组合的工具——搜索、按艺术家／专辑细化搜索、下载并生成哈希、解析任意 URL 的许可证、反向图片搜索，以及对来源页面进行分类——让 Agent 可以在一次对话中从提示词获取带署名信息的素材。

• 25 个提供商，其中 19 个默认启用，且许多无需密钥
• 许可证优先排序：CC0 排在最前；仅基于启发式规则的结果置信度低于 0.5
• 始终包含署名信息：一个 attributionLine 字符串，可直接用于提示工具提示或页脚鸣谢
• 免费层无需 API 密钥即可使用 Wikimedia 和 Openverse；要覆盖全部提供商，可按需添加各提供商的密钥

---

安装

一行命令（推荐）

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

如缺少 bun，则安装 bun；构建服务，将 webfetch 符号链接到 $PATH，并将 MCP 配置块合并到 ~/.claude/settings.json。

Claude Desktop / Claude Code

添加到 ~/.claude/settings.json：

{
  "mcpServers": {
    "webfetch": {
      "command": "bun",
      "args": ["run", "/path/to/webfetch/packages/mcp/src/index.ts"]
    }
  }
}

Cursor

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "webfetch": {
      "command": "bun",
      "args": ["run", "/path/to/webfetch/packages/mcp/src/index.ts"]
    }
  }
}

Cline

将以下内容粘贴到 Cline 的 MCP 设置 JSON 中（VSCode 侧边栏 → Cline → MCP Servers）：

{
  "mcpServers": {
    "webfetch": {
      "command": "bun",
      "args": ["run", "/path/to/webfetch/packages/mcp/src/index.ts"],
      "disabled": false,
      "autoApprove": ["search_images", "search_artist_images", "search_album_cover", "probe_page"]
    }
  }
}

将 /path/to/webfetch 替换为克隆路径（安装器运行后默认为 ~/.webfetch/repo）。

---

工具

工具	说明	关键参数
search_images	在 25 个提供商中进行联合搜索。返回带有许可证和署名信息的最佳候选结果。不下载图片。批量处理时，使用 CLI 交接：webfetch batch --jsonl。	query、providers[]、licensePolicy、minWidth、minHeight
search_artist_images	专门搜索艺术家图片，并根据类型路由到相应提供商：portrait、album、logo、performing。	artist、kind、providers[]
search_album_cover	通过 MusicBrainz CAA + iTunes + Spotify 获取标准专辑封面。结果标记为 EDITORIAL_LICENSED。	artist、album
download_image	将 URL 下载到本地磁盘缓存。限制为 20 MB，检查内容类型，生成 SHA-256 哈希，并强制执行主机屏蔽列表。	url、maxBytes、cacheDir
fetch_with_license	通过主机启发式规则和页面元数据（<link rel=license>、dc.rights、OG 标签）解析任意 URL 的许可证。	url、probe（同时下载字节内容）
find_similar	对参考 URL 执行反向图片搜索。需要 SERPAPI_KEY。返回线索——正式使用前请先核实。	url、providers[]
probe_page	枚举网页上的所有 <img>，推断其尺寸及每张图片的启发式许可证。遵循 robots.txt。	url、respectRobots

许可证标签

结果会带有以下标签之一：CC0 · PUBLIC_DOMAIN · CC_BY · CC_BY_SA · UNSPLASH_LICENSE · PEXELS_LICENSE · PIXABAY_LICENSE · EDITORIAL_LICENSED · PRESS_KIT_ALLOWLIST · UNKNOWN（默认拒绝）。若不接受平台许可证或编辑用途许可证，请使用 open-only。

迁移说明：Unsplash、Pexels 和 Pixabay 不再标记为 CC0。 Agent 应将 UNSPLASH_LICENSE、PEXELS_LICENSE 和 PIXABAY_LICENSE 视为平台许可证结果，而非知识共享／公有领域结果。

批量交接

MCP 工具旨在供 Agent 交互式调用。对于数百或数千条查询，请让 Agent 将任务交给 CLI：

webfetch batch --file queries.txt --jsonl --continue-on-error --candidates 3

输入行格式为 query 或 query<TAB>provider-a,provider-b。每个输出行包含 index、query、status、candidateCount、candidates、top、downloads 和提供方诊断信息。

---

身份验证 / 环境变量

提供方	环境变量	有免费套餐？
Wikimedia Commons	—	有（无需密钥）
Openverse	—	有（无需密钥）
Unsplash	UNSPLASH_ACCESS_KEY	Demo 密钥受速率限制
Pexels	PEXELS_API_KEY	提供免费套餐
Pixabay	PIXABAY_API_KEY	提供免费套餐
Spotify	SPOTIFY_CLIENT_ID + SPOTIFY_CLIENT_SECRET	需要开发者应用
Brave Search	BRAVE_API_KEY	提供免费套餐
SerpApi	SERPAPI_KEY	find_similar 必需
Bright Data 托管浏览器	BRIGHTDATA_API_TOKEN	可选的服务端/云端备用方案

MusicBrainz CAA 和 iTunes 无需密钥。缺少密钥时，该提供方会自动跳过，其他提供方仍会响应。

---

示例提示词

安装后，可在 Claude Code 或 Cursor 中尝试：

Find me a CC-licensed portrait of Miles Davis I can use on an album liner page.

Search for album artwork for "Kind of Blue" by Miles Davis and show me the attribution line.

Probe the page at https://commons.wikimedia.org/wiki/File:Miles_Davis.jpg and tell me if I can use it commercially.

---

要求

• Node ≥ 18 或 Bun ≥ 1.0
• 基本使用无需 API 密钥（Wikimedia + Openverse 可满足大多数编辑需求）

---

链接

• 主页 + 文档：getwebfetch.com
• 一行安装指南：docs/QUICKSTART.md
• 提供方覆盖矩阵：docs/PROVIDERS.md
• 许可政策详情：docs/LICENSE_POLICY.md
• 各 Agent 安装指南：Claude Code · Cursor · Cline
• 问题反馈：github.com/ashlrai/webfetch/issues