内容
# 图片银行 MCP
允许 AI 编程代理（如 Claude Code、Codex、Cursor、Antigravity、Cline、Windsurf 和任何 MCP 兼容客户端）搜索免费的库存照片，下载并直接转换为 **WebP**，无需占位符、无需热链接、无需手动搜索图片。
为网页开发者打造：代理询问“ artisan bread 的英雄照片”，获取真实结果，保存优化的 `public/images/hero-artisan-bread.webp`，并写入指向它的 `<Image>` 标签。完成。
## 工具
| 工具 | 功能 |
|---|---|
| `search_images` | 并行搜索一个或所有配置的提供商。返回预览 URL、下载 URL、尺寸、作者和归属链接。支持方向和主色调过滤。 |
| `download_image` | 下载结果，转换为 WebP（质量和最大宽度可配置），保存在项目中，返回 `<Image src>` 的路径。当需要时，自动触发 Unsplash 下载跟踪端点。 |
| `optimize_local_image` | 适用于本地文件的相同管道。当客户端用自己的图片替换库存图片时使用，以保持性能一致。 |
## 要求
- Node.js >= 18.17
- 至少一个 API 密钥（全部免费）：
- Pexels：https://www.pexels.com/api/
- Unsplash：https://unsplash.com/developers （使用 **Access Key**）
- Pixabay：https://pixabay.com/api/docs/
> 首次安装可能需要更长时间：`sharp`（图像处理）下载适用于您平台的预构建原生二进制文件。这是正常的。
## 安装
推荐使用 `npx` — 无需手动安装，每个客户端只需指向该包：
```jsonc
"command": "npx",
"args": ["-y", "imagebank-mcp"]
```
API 密钥放在每个客户端配置的 `env` 块中。**永远不要将密钥提交到仓库中。** 只有您设置的密钥才会被使用；缺少的提供商将被跳过。
### Claude Code
每个项目（`.mcp.json` 在项目根目录）或全局（`~/.claude.json`）：
```json
{
"mcpServers": {
"image-banks": {
"command": "npx",
"args": ["-y", "imagebank-mcp"],
"env": {
"PEXELS_API_KEY": "your_key",
"UNSPLASH_ACCESS_KEY": "your_key",
"PIXABAY_API_KEY": "your_key"
}
}
}
}
```
或通过 CLI：
```bash
claude mcp add image-banks -e PEXELS_API_KEY=your_key -e UNSPLASH_ACCESS_KEY=your_key -e PIXABAY_API_KEY=your_key -- npx -y imagebank-mcp
```
### Cursor
`.cursor/mcp.json` 在项目中（或 `~/.cursor/mcp.json` 全局）。与上面的 Claude Code 具有相同的 JSON 结构。
### OpenAI Codex CLI
`~/.codex/config.toml`:
```toml
[mcp_servers.image-banks]
command = "npx"
args = ["-y", "imagebank-mcp"]
[mcp_servers.image-banks.env]
PEXELS_API_KEY = "your_key"
UNSPLASH_ACCESS_KEY = "your_key"
PIXABAY_API_KEY = "your_key"
```
### Antigravity
代理设置 → MCP 服务器 → 添加服务器。使用与 Claude Code 相同的 JSON 结构（`mcpServers` 块，包含 `command`、`args`、`env`）。
### Cline / Roo Code (VSCode)
MCP 设置文件 (`cline_mcp_settings.json`)：与 Claude Code 具有相同的 JSON 结构。
### Windsurf
`~/.codeium/windsurf/mcp_config.json`：与 Claude Code 具有相同的 JSON 结构。
### Gemini CLI
`~/.gemini/settings.json`，在 `mcpServers` 内：与 Claude Code 具有相同的 JSON 结构。
> 配置文件位置在客户端版本之间可能会发生变化。如果上述路径与您的安装不匹配，请检查客户端的 MCP 文档 — 服务器块本身（`command`/`args`/`env`）在所有地方都是相同的。
## 用法
您很少会显式调用工具。在正常使用中，代理会自行决定：
> “为面包店构建英雄部分，配有新鲜出炉的酸面包照片。”
代理将调用 `search_images`（英文查询，`orientation: landscape`），选择一个结果，调用 `download_image`，并使用返回的本地路径编写组件。
显式提示也有效：
```
在 unsplash 上搜索 6 张“现代牙科诊所接待处”的风景照片，
以 85 的质量下载最好的一个作为 hero-clinic-reception。
```
### 推荐的代理指南
添加到您的 `CLAUDE.md` / 规则文件中，以获得最佳行为：
```
图片：当设计需要图片而客户未提供时，
使用图片银行 MCP（search_images 然后 download_image）。用英语搜索。
永远不要热链接库存网址；始终下载到 public/images。
优先使用客户提供的图片（优化它们以 optimize_local_image）。
避免在付费广告中使用带有明显面孔的库存图片。
```
## 图片许可（阅读一次）
所有三个提供商都允许 **免费商业使用，无需在最终网站上注明出处**。不过：
- **Unsplash API 规则**：当实际使用图片时，必须 ping 下载端点。`download_image` 在您传递 `trackDownloadUrl` 时会自动执行此操作。
- **Pixabay**：禁止永久热链接 — 您必须自行托管。此服务器默认下载，因此您默认符合要求。
- **模型发布**：没有一个平台验证出现在图片中的人员的同意。避免在付费广告中使用带有可识别面孔的图片；对于普通网站部分来说是可以的。
- 不需要注明出处，但表示感谢 — 如果您想注明出处，`attributionUrl` 和 `author` 字段始终会返回。
这不是法律建议；请为您的特定情况查看每个提供商的许可证。
## 安全
- **SSRF 保护**：`download_image` 仅接受 `pexels.com`、`unsplash.com`、`pixabay.com` 和子域上的 `https` URL。内部 IP、云元数据端点和任意主机都被拒绝。
- **路径遍历保护**：文件名被清理为 kebab-case；输出和输入路径必须在工作目录内解析。
- **大小和类型限制**：下载上限为 25 MB；验证内容类型；设置 sharp 像素炸弹限制。
- **密钥**：仅从 env 读取，永不记录，永不回显在工具输出中。
- 通过 stdio 在本地运行。没有任何内容被托管；除了您配置的提供商的 API 调用外，您的机器上没有数据离开。
## 本地开发
```bash
git clone https://github.com/romuloquintanilha/imagebank-mcp
cd imagebank-mcp
npm install
npm run build
npm test # 单元测试 + 真实 MCP 协议 + sharp 管道测试
npm run inspector # 交互式 UI，用于手动调用工具
```
对于检查器，请先导出您的密钥（`export PEXELS_API_KEY=...`）。
## 许可证
MIT — 请参阅 [LICENSE](./LICENSE)。代码是 MIT 许可的；您下载的图片受每个提供商自己的许可证约束。
