Stock Images MCP

Stock Images MCP

用于从 Pexels、Unsplash 和 Pixabay 搜索和下载图库图片的 MCP（模型上下文协议）服务。

功能

• search_images：搜索一个或所有已配置的提供商；会分别报告各提供商的部分失败情况
• download_image：将图片安全地下载到本地文件夹

设置

获取 API 密钥（至少需要一个）

提供商	环境变量	获取密钥
Pexels	PEXELS_API_KEY	https://www.pexels.com/api/
Unsplash	UNSPLASH_API_KEY	https://unsplash.com/developers
Pixabay	PIXABAY_API_KEY	https://pixabay.com/api/docs/

可选：STOCK_IMAGES_DOWNLOAD_DIR — download_image 写入文件的位置（默认值为 ./downloads）。

Claude Code / Cursor / Claude Desktop

添加到 MCP 配置（~/.claude/mcp.json、~/.cursor/mcp.json 或 claude_desktop_config.json）：

{
  "mcpServers": {
    "stock-images": {
      "command": "npx",
      "args": ["-y", "stock-images-mcp"],
      "env": {
        "PEXELS_API_KEY": "your-key-here",
        "UNSPLASH_API_KEY": "your-key-here",
        "PIXABAY_API_KEY": "your-key-here"
      }
    }
  }
}

需要 Node.js 22+。

Docker

docker build -t stock-images-mcp .
docker run -i --rm -e PEXELS_API_KEY=xxx -v "$PWD/downloads:/downloads" stock-images-mcp

从源代码构建

git clone https://github.com/jeanpfs/stock-images-mcp.git
cd stock-images-mcp
npm ci && npm run build
PEXELS_API_KEY=xxx node dist/index.js

工具

search_images

在已配置的提供商中搜索图库图片。

参数：

• query（必填）：搜索词
• provider："pexels"、"unsplash"、"pixabay" 或 "all"（默认值："all"）
• count：每个提供商返回的结果数（默认值为 5，最大值为 20）
• orientation："landscape"、"portrait" 或 "square"

每个结果包含 id、provider、url、thumbnail、description、author、authorUrl、downloadUrl、width、height。将 downloadUrl 传给 download_image。

download_image

将图片下载到下载目录。

参数：

• url（必填）：位于 pexels.com、unsplash.com 或 pixabay.com 上的 https 图片 URL（使用 search_images 返回的 downloadUrl）
• filename：输出名称 — 仅限字母、数字、_、-、.；如果缺少扩展名，将根据内容类型添加（未提供时自动生成）
• folder：下载目录中的子文件夹

行为和限制：

• 下载目录为 ./downloads，或设置了 STOCK_IMAGES_DOWNLOAD_DIR 时使用其指定目录。会拒绝任何逃逸出该目录的路径（包括通过符号链接逃逸的路径）。
• 仅保存 image/* 响应；最大 50 MiB；超时 30 秒；仅跟随重定向到允许的主机。
• 永不覆盖已有文件。
• Unsplash 下载需要 UNSPLASH_API_KEY：该工具会调用 Unsplash 的下载端点，这是其 API 指南的要求。

错误

失败时返回 isError: true。如果部分提供商失败、其他提供商成功，search_images 也会返回按提供商分类的 errors 列表。提供商请求在 10 秒后超时；遇到网络错误、429 和 502/503/504 时会重试。

署名和许可

图片受各提供商的许可条款约束。按提供商要求标注摄影师（为此会返回 author 和 authorUrl），并查看许可条款：Pexels、Unsplash、Pixabay。

开发

npm ci
npm run lint && npm run format:check && npm run typecheck && npm test

请参阅 CONTRIBUTING.md、CODE_OF_CONDUCT.md 和 SECURITY.md（请私下报告漏洞，不要在公开议题中报告）。

许可证

MIT