Stock Image MCP

stock-image-mcp

一个 MCP 服务，可让 Claude Code（或任何兼容 MCP 的 Agent）通过工具调用搜索和下载图库图片，适合在撰写 SEO 博客文章或其他内容时查找图片。

提供商

提供商	API 类型	需要密钥	默认速率限制
Unsplash	官方	是	演示版 50 次/小时，生产版 5000 次/小时
Pexels	官方	是	200 次/小时
Pixabay	官方	是	100 次/60 秒
Freepik	官方	是	可配置（取决于套餐）
StockVault	官方	是	可配置（未公开说明，默认值较为保守）
Burst (Shopify)	非官方抓取	否	自行设定，默认较为克制

Burst 没有公共 API。此处以尽力而为的 HTML 抓取器形式提供，并在代码中明确标注为不受支持——该功能发生的任何故障都会被捕获，并以空结果报告，而不会导致 search_all_images 出错。

安装

每位用户都在本地运行服务，并提供自己的提供商 API 密钥——不会共享托管，也不会集中保管密钥。

使用 Claude Code：

claude mcp add stock-image-mcp \
  -e UNSPLASH_ACCESS_KEY=... \
  -e UNSPLASH_TIER=demo \
  -e PEXELS_API_KEY=... \
  -e PIXABAY_API_KEY=... \
  -e FREEPIK_API_KEY=... \
  -e FREEPIK_REQUESTS_PER_MINUTE=60 \
  -e STOCKVAULT_API_KEY=... \
  -e STOCKVAULT_REQUESTS_PER_HOUR=60 \
  -e BURST_REQUESTS_PER_MINUTE=10 \
  -e DEFAULT_PROVIDER=pexels \
  -e DOWNLOAD_DIR=./downloads \
  -- uvx stock-image-mcp

使用 OpenAI Codex CLI：

codex mcp add stock-image-mcp \
  --env UNSPLASH_ACCESS_KEY=... \
  --env UNSPLASH_TIER=demo \
  --env PEXELS_API_KEY=... \
  --env PIXABAY_API_KEY=... \
  --env FREEPIK_API_KEY=... \
  --env FREEPIK_REQUESTS_PER_MINUTE=60 \
  --env STOCKVAULT_API_KEY=... \
  --env STOCKVAULT_REQUESTS_PER_HOUR=60 \
  --env BURST_REQUESTS_PER_MINUTE=10 \
  --env DEFAULT_PROVIDER=pexels \
  --env DOWNLOAD_DIR=./downloads \
  -- uvx stock-image-mcp

使用 Gemini CLI：

gemini mcp add stock-image-mcp \
  -e UNSPLASH_ACCESS_KEY=... \
  -e UNSPLASH_TIER=demo \
  -e PEXELS_API_KEY=... \
  -e PIXABAY_API_KEY=... \
  -e FREEPIK_API_KEY=... \
  -e FREEPIK_REQUESTS_PER_MINUTE=60 \
  -e STOCKVAULT_API_KEY=... \
  -e STOCKVAULT_REQUESTS_PER_HOUR=60 \
  -e BURST_REQUESTS_PER_MINUTE=10 \
  -e DEFAULT_PROVIDER=pexels \
  -e DOWNLOAD_DIR=./downloads \
  -- uvx stock-image-mcp

也可以使用 uvx 手动将其添加到 MCP 配置中（无需克隆或安装步骤——uvx 会在首次运行时从 PyPI 获取软件包）：

{
  "mcpServers": {
    "stock-image-mcp": {
      "command": "uvx",
      "args": ["stock-image-mcp"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "...",
        "UNSPLASH_TIER": "demo",
        "PEXELS_API_KEY": "...",
        "PIXABAY_API_KEY": "...",
        "FREEPIK_API_KEY": "...",
        "FREEPIK_REQUESTS_PER_MINUTE": "60",
        "STOCKVAULT_API_KEY": "...",
        "STOCKVAULT_REQUESTS_PER_HOUR": "60",
        "BURST_REQUESTS_PER_MINUTE": "10",
        "DEFAULT_PROVIDER": "pexels",
        "DOWNLOAD_DIR": "./downloads"
      }
    }
  }
}

只有 UNSPLASH_ACCESS_KEY、PEXELS_API_KEY、PIXABAY_API_KEY、FREEPIK_API_KEY 和 STOCKVAULT_API_KEY 是实际的密钥——只需设置要启用的提供商对应的密钥，并删除其余密钥；search_all_images 会跳过未提供密钥的提供商，而直接通过 search_stock_images 查询这些提供商时则会被拒绝。其余变量都是可选的调优参数，上方列出了它们的默认值——完整列表请参见 .env.example。

工具

• search_stock_images(query, provider="default", orientation=None, per_page=10, page=1)
• search_all_images(query, orientation=None, per_page=5) — 并发查询所有已配置的提供商
• get_best_image(query, provider="default")
• download_image(url, dest_path, provider=None) — 将图片保存到本地；如果图片来自之前的搜索，则返回署名文本
• get_attribution(provider, image_id)
• get_rate_limit_status(provider=None)

使用方法

你无需直接调用这些工具，只需与 Agent 对话，它会根据你的请求和上方的工具说明，决定何时使用某个工具。以下几点值得注意：

• 使用普通英文提问即可。“帮我找 3 张适合博客文章的山景照片”足以触发 search_all_images（如果你指定了提供商，则会触发 search_stock_images）。“将第一个 Unsplash 搜索结果下载到 ./images/hero.jpg”会触发 download_image。“我本小时还剩多少次 Pexels 请求？”会触发 get_rate_limit_status。
• search_stock_images 需要指定提供商（或使用 "default"）；search_all_images 则会查询你已配置密钥的所有提供商并合并结果。如果你在意使用哪个提供商，请说“只搜索 Pexels”或类似的话。
• 有几个提供商（尤其是 Unsplash 和 Pexels）要求你在公开场合使用图片时注明出处。适用时，download_image 会在文件旁附上注明出处的文本——你需要自行将其粘贴到图片最终展示的位置，服务不会替你完成这一步。
• 想要手动调用工具，而不是通过对话调用？请参阅下方“开发”部分中的 MCP Inspector 章节。

本地开发

如果要基于克隆的仓库进行开发，而不是使用已发布的程序包：

uv sync
cp .env.example .env   # fill in the API keys for providers you want enabled
uv run stock-image-mcp

将 Claude 配置指向本地检出目录，而不是 uvx：

{
  "mcpServers": {
    "stock-image-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/stock-image-mcp",
        "run",
        "stock-image-mcp"
      ],
      "env": {
        "UNSPLASH_ACCESS_KEY": "...",
        "UNSPLASH_TIER": "demo",
        "PEXELS_API_KEY": "...",
        "PIXABAY_API_KEY": "...",
        "FREEPIK_API_KEY": "...",
        "FREEPIK_REQUESTS_PER_MINUTE": "60",
        "STOCKVAULT_API_KEY": "...",
        "STOCKVAULT_REQUESTS_PER_HOUR": "60",
        "BURST_REQUESTS_PER_MINUTE": "10",
        "DEFAULT_PROVIDER": "pexels",
        "DOWNLOAD_DIR": "./downloads"
      }
    }
  }
}

开发

uv run pytest              # test suite (mocked HTTP, no live keys needed)
uv run ruff check .         # lint
uv run ruff format .        # format
uv run mypy src             # type check

要使用真实提供商进行测试，请使用 MCP Inspector：

npx @modelcontextprotocol/inspector uv run stock-image-mcp