Stocky

Stocky
查找精美的免版税图库图片 📸

Stocky 是一款 MCP 服务，让 AI 助手能够从 Pexels 和 Unsplash 搜索、查看并下载免版税的图库摄影作品。

🆕 版本 2.0 — 已在使用 Stocky？请阅读本文

你的 MCP 客户端配置仍然有效。 如果配置指向 stocky_mcp.py， 该文件仍然存在，也仍然可以启动服务。升级不会造成任何问题。

但 pip install -r requirements.txt 将会失败——该文件已不存在， setup.py 也已移除。从源代码检出目录安装时，请改用 uv sync 或 pip install -e .。请参阅从 1.x 升级，了解两分钟快速说明； 如需了解全部变更，请参阅 CHANGELOG。

主要变更：移除了 pycurl（不再出现 C 构建错误），搜索现在会并发运行， 失败的提供商现在会报告失败原因，而不是不返回任何结果，并且要求使用 Python 3.10+。

✨ 功能

• 🔍 多提供商搜索 — 并发查询 Pexels 和 Unsplash
• 📊 丰富的元数据 — 尺寸、摄影师、标签和每种图片尺寸
• ⚖️ 遵循许可要求 — 生成各提供商要求的署名信息，并按 Unsplash 的 API 指南要求报告下载情况
• ⏱️ 搜索缓存 — 短暂的 TTL 缓存可避免重复查询消耗配额
• 🛡️ 如实报告错误 — 提供商发生故障时会报告错误，而不会悄悄返回“无结果”
• 🎯 筛选条件 — 方向、颜色和排序，并按各提供商的要求进行验证

精美图库摄影作品，触手可及 示例图片仅用于演示

可通过多个提供商获取的壮丽风景

照片由 Simon Berger 拍摄，发布于 Unsplash

🚀 快速开始

1. 获取 API 密钥

两者均可免费获取：

只需一个密钥即可——Stocky 会使用已配置的提供商运行。

2. 将其添加到 MCP 客户端

推荐的配置无需安装：

{
  "mcpServers": {
    "stocky": {
      "command": "uvx",
      "args": ["stocky-mcp"],
      "env": {
        "PEXELS_API_KEY": "your_pexels_key",
        "UNSPLASH_ACCESS_KEY": "your_unsplash_key"
      }
    }
  }
}

uv tool install stocky-mcp     # or: pipx install stocky-mcp

{
  "mcpServers": {
    "stocky": {
      "command": "stocky-mcp",
      "env": { "PEXELS_API_KEY": "your_pexels_key" }
    }
  }
}

{
  "mcpServers": {
    "stocky": {
      "command": "python",
      "args": ["/path/to/stocky/stocky_mcp.py"],
      "env": { "PEXELS_API_KEY": "your_pexels_key" }
    }
  }
}

Stocky 会从启动它的客户端所处的环境中读取配置。 它不会自行加载 .env 文件，因此密钥必须放在上方的 env 区块中。

⚙️ 配置

建议设置 STOCKY_DOWNLOAD_ROOT。下载路径来自模型生成的工具调用，此设置可将写入限制在一个目录中。Stocky 始终会拒绝扩展名不是图片的文件，并在获取图片前验证提供方的图片 URL 是否为公开的 HTTP(S) 地址，但下载根目录是最严格的控制措施。

📖 用法

为你的项目找到完美图片

Stocky 提供三个 MCP 工具。你无需直接调用它们——你用自然语言提出请求时，客户端会调用这些工具。

搜索日出时薄雾笼罩的松林照片。

在 Pexels 中查找 30 张横向山景照片。

将 pexels_123456 下载为中等尺寸，保存到 ~/Pictures/mountain.jpg

🛠️ 工具

search_stock_images

返回按提供方分组的结果，以及 total_results；如果有提供方调用失败，还会返回说明失败提供方及原因的 errors 映射。

无效的 orientation 或 color 会被丢弃，而不会转发：Pexels 会静默忽略无效筛选条件并仍然返回 200，这可能会掩盖错误；而 Unsplash 则会直接以 HTTP 400 拒绝请求。

get_image_details

download_image

如果提供方不支持所请求的尺寸，将使用最接近的可用尺寸，而不会直接失败。

资源

stock-images://help — 助手可按需读取的用法指南。

⚖️ 许可与署名

图片可免费使用，但两家提供商都要求署名，作为 API 访问的条件。这不是可选项，而且本文档的旧版本错误地暗示 Pexels 不要求署名。

Pexels 要求在展示 API 结果的任何地方醒目地添加指向 Pexels 的链接，并建议尽可能注明摄影师。

Unsplash 要求同时注明摄影师和 Unsplash，链接中还必须包含 UTM 参数；图片必须通过 API 返回的 URL 热链接，而不是重新托管。

设置 ENABLE_ATTRIBUTION_LINKS=true 后，每条结果都会包含一个 attribution 区块，其中提供了符合相应提供商格式的现成 text 和 html。

关于 download_image 的说明。 将 Unsplash 图片数据保存到磁盘或以 Base64 编码的形式返回，都与 Unsplash 的热链接要求相冲突。每当你下载 Unsplash 图片时，Stocky 都会调用强制要求的下载报告端点；但如果你要在应用中展示图片，请使用搜索结果中的热链接 URL，而不是下载图片。

请阅读完整条款：Pexels · Unsplash

⬆️ 从 1.x 升级

2.0 版对项目进行了重组。现有 MCP 客户端配置仍可正常使用——根目录中的 stocky_mcp.py 被刻意保留为启动器——但安装方式已改变，部分行为也有意作了调整。

你需要做什么

如果你通过 uvx 或已安装的控制台脚本运行它，无需操作。升级后继续使用即可。

如果你从源代码检出目录运行它，请重新安装。requirements.txt、setup.py 和 setup.cfg 已由 pyproject.toml 取代：

git pull
uv sync                     # or: pip install -e .

现在运行 pip install -r requirements.txt 会失败——该文件已不存在。

检查你的 Python 版本。 2.0 需要 Python 3.10+。旧版 setup.py 声称支持 3.8，但 mcp SDK 一直要求 3.10，因此该声明实际上从未可行。

考虑改用 uvx。 它无需安装任何内容，还能避免整类“编辑器启动时用了哪个解释器？”的启动故障：

{
  "mcpServers": {
    "stocky": {
      "command": "uvx",
      "args": ["stocky-mcp"],
      "env": { "PEXELS_API_KEY": "your_pexels_key" }
    }
  }
}

底层有哪些变化

可能影响你代码的一点

仅当你以编程方式解析 Stocky 的响应时。 现在，搜索失败时会返回一个 errors 映射，标明提供商及失败原因；以前则会返回空结果列表：

{
  "query": "mountains",
  "results": { "pexels": [], "unsplash": [ /* ... */ ] },
  "errors": { "pexels": "pexels rejected the API key (HTTP 401)..." }
}

如果你把“结果为空”视为“没有匹配项”，也要检查 errors——否则，密钥失效会看起来像是查询没有结果。这是修复，不是回归，但确实是可见的变化。

工具接口的其他部分没有变化：search_stock_images、get_image_details 和 download_image 接收的参数与以往相同，因此现有提示词和工作流不受影响。

🧑‍💻 开发

git clone https://github.com/joelio/stocky.git
cd stocky
uv sync --group dev

uv run pytest -m "not integration"   # unit tests, no network
uv run pytest -m integration         # needs real API keys
uv run ruff check . && uv run ruff format --check .
uv run mypy

更多信息请参阅 CONTRIBUTING.md。

🐛 故障排查

客户端报告启动超时 几乎总是启动问题，而不是 Stocky 的错误。通过 GUI 启动的客户端通常只有精简的 PATH，因此可能找不到 uvx 或虚拟环境中的 python——请使用绝对路径，或者使用系统范围安装了 uv 的 uvx。你可以自行重现握手过程：

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  | stocky-mcp

JSON 响应表示服务正常。请注意，stdout 承载协议，因此 Stocky 会将所有日志发送到 stderr——在那里打印其他内容会破坏数据流。

“未配置图像提供商” 没有密钥传到服务端。密钥必须放在客户端配置的 env 块中；名称区分大小写。

提供商返回错误 检查响应中的 errors。现在，身份验证失败、速率限制和超时都会明确报告，不会再表现为结果集为空。

Pexels 似乎接受了无效密钥 确实如此。Pexels 对格式错误的密钥会返回 200，因此拼写错误看起来可能像是有效的。如果结果不对，请直接验证密钥。

速率限制

🤝 贡献

欢迎贡献——请参阅 CONTRIBUTING.md。对于重大变更，请先提交议题讨论方案。

🙏 致谢

• 感谢 Pexels 和 Unsplash 提供免费 API
• 基于 Model Context Protocol 构建