Unsplash MCP Server

unsplash-mcp-server

面向生产环境的 Model Context Protocol（MCP）Unsplash API 服务。它为 AI 助手（Claude Desktop、Claude Code、Cursor、VS Code、Windsurf 和任何 MCP 客户端）提供工具，用于搜索和获取 Unsplash 照片、合集、主题、用户及统计数据，并内置符合 Unsplash 指南的功能（可直接使用的署名信息和下载跟踪）。通过 OAuth 登录一次后，还可管理自己的个人资料、合集和照片元数据。

重要

非官方项目。 本项目与 Unsplash 无关，未经其认可或赞助。“Unsplash”是其各自所有者的商标。使用本项目时，您使用的是自己的 Unsplash API 账号，并有责任遵守 Unsplash API 条款和指南。

目录

• 功能
• 快速开始
• 交互示例
• 配置
• OAuth 登录（可选）
• 工具
  • 工具参考
  • 输出格式
  • 资源和提示词
• 提示词示例
• 署名和合规
• 速率限制
• Unsplash 文本的处理
• 隐私和安全
• 故障排除
• 常见问题
• 要求
• 兼容性
• 路线图
• 贡献
• 联系和社区
• 许可证

功能

• 29 个工具，涵盖照片、搜索、用户、合集、主题、统计数据和个人资料——开箱即用时有 21 个只读工具，登录后还可使用 8 个写入/me 工具（登录）。
• 内置合规功能——每张照片都附带可直接使用的署名信息（纯文本和带 UTM 参数的 HTML），并提供专用的 unsplash_track_download 工具，满足下载跟踪指南要求。
• 内容安全——搜索和随机照片默认使用 content_filter=high。
• 灵活的图片 URL——每张照片都返回 raw/full/regular/small/thumb 尺寸，以及可用于自定义尺寸的 raw imgix 基础 URL（?w=&h=&q=&fm=&fit=）。
• 节省令牌的输出——将完整的 Unsplash 响应精简为紧凑格式（URL 和元数据以文本形式呈现，不包含 base64 图片数据），以缩小模型上下文。
• 健壮可靠——以 MCP isError 结果返回类型化错误，便于模型恢复；并支持重试/退避、超时、403 每小时限额处理和速率限制提示。
• 安全可靠——所有错误输出都会隐藏访问密钥；对下载 URL 实施 SSRF 防护，并提供不可信文本处理指南，以防御间接提示注入。
• 精简现代——ESM、Node 20+、通过 npx 即可免安装运行，且不收集遥测数据。

快速开始

1. 获取 Unsplash 访问密钥

在 unsplash.com/developers 注册应用 → 选择 New Application → 接受 API 条款 → 复制应用的 Access Key（不是 Secret Key）。新应用默认使用 Demo 级别（每小时 50 次请求）；Production 级别（每小时 5,000 次请求）需要 Unsplash 在应用控制面板中审核。请参阅速率限制。

2. 将服务添加到 MCP 客户端

Claude Desktop — 编辑 claude_desktop_config.json：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "unsplash": {
      "command": "npx",
      "args": ["-y", "@hanoak/unsplash-mcp-server"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_access_key",
        "UNSPLASH_APP_NAME": "your_registered_app_name"
      }
    }
  }
}

重启客户端。请参阅配置，了解所有受支持的变量。

claude mcp add unsplash \
  --env UNSPLASH_ACCESS_KEY=your_access_key \
  --env UNSPLASH_APP_NAME=your_registered_app_name \
  -- npx -y @hanoak/unsplash-mcp-server

{
  "servers": {
    "unsplash": {
      "command": "npx",
      "args": ["-y", "@hanoak/unsplash-mcp-server"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_access_key",
        "UNSPLASH_APP_NAME": "your_registered_app_name"
      }
    }
  }
}

UNSPLASH_ACCESS_KEY=your_access_key npx -y @hanoak/unsplash-mcp-server

3. 试用

重启客户端并询问：

“在 Unsplash 上帮我找一张山景照片，并显示署名信息。”

交互示例

一个典型的流程：模型调用 unsplash_search_photos，挑选一条结果，展示图片及其署名，并在实际使用照片时调用 unsplash_track_download。

你： 找一张雾气笼罩的松树林风景照，并注明摄影师。

助手： （调用 unsplash_search_photos，参数为 query: "foggy pine forest"、orientation: "landscape"，挑选最佳结果，然后调用 unsplash_track_download 并传入其 download_location） 这是一个很好的匹配结果——照片由 Jane Doe 拍摄，来自 Unsplash——并附有可直接嵌入的署名信息和图片 URL。

每个工具都会返回精简的 JSON 载荷。以下是单张照片结果的结构（示例值）：

{
  "photo": {
    "id": "Dwu85P9SOIk",
    "description": "brown rocky mountain under blue sky during daytime",
    "width": 6000,
    "height": 4000,
    "color": "#734940",
    "blur_hash": "L6Pj0^i_.AyE_3t7t7R**0o#DgR4",
    "urls": {
      "raw": "https://images.unsplash.com/photo-1465…?ixid=…",
      "full": "https://images.unsplash.com/photo-1465…?ixid=…&q=85",
      "regular": "https://images.unsplash.com/photo-1465…?ixid=…&w=1080",
      "small": "https://images.unsplash.com/photo-1465…?ixid=…&w=400",
      "thumb": "https://images.unsplash.com/photo-1465…?ixid=…&w=200"
    },
    "photo_page": "https://unsplash.com/photos/Dwu85P9SOIk",
    "download_location": "https://api.unsplash.com/photos/Dwu85P9SOIk/download?ixid=…",
    "photographer": {
      "name": "Jane Doe",
      "username": "janedoe",
      "profile": "https://unsplash.com/@janedoe"
    },
    "attribution": {
      "text": "Photo by Jane Doe on Unsplash",
      "html": "Photo by <a href=\"https://unsplash.com/@janedoe?utm_source=your_app&utm_medium=referral\">Jane Doe</a> on <a href=\"https://unsplash.com/?utm_source=your_app&utm_medium=referral\">Unsplash</a>",
      "photographerName": "Jane Doe",
      "photographerUrl": "https://unsplash.com/@janedoe?utm_source=your_app&utm_medium=referral",
      "unsplashUrl": "https://unsplash.com/?utm_source=your_app&utm_medium=referral"
    }
  },
  "rate_limit": { "limit": 50, "remaining": 49 }
}

所有配置均通过环境变量完成——无需配置文件，也没有用于指定机密信息的标志。

支持 CLI 标志：--version 和 --help（例如 npx @hanoak/unsplash-mcp-server --version）。login/logout 是子命令，不是标志——见下文。

OAuth 登录（可选）

只需设置 UNSPLASH_ACCESS_KEY，即可开箱使用 21 个核心工具。若还要使用 8 个写入/me 工具（更新个人资料、管理合集、编辑照片元数据），请通过 OAuth 登录一次：

1. 在 unsplash.com/oauth/applications 的应用页面中，将 http://localhost:8734/callback 添加为重定向 URI，并复制 Secret key。

2. 在 shell 中设置 UNSPLASH_ACCESS_KEY 和 UNSPLASH_SECRET_KEY（不能只在 MCP 客户端配置中设置——login 需要从终端运行）。

3. 运行：

   npx @hanoak/unsplash-mcp-server login
   

   这会打开浏览器并跳转到 Unsplash 的授权页面，在短暂运行的本地服务上接收重定向，将授权码换成用户访问令牌，并将其保存到 ~/.config/unsplash-mcp-server/credentials.json（文件权限仅所有者可访问）。Unsplash 用户访问令牌 不会过期，因此只需执行一次——无需定期重新授权。

4. 重启 MCP 客户端。现在即可使用 8 个写入/me 工具；无论是否登录，21 个只读工具都不受影响。

随时运行 npx @hanoak/unsplash-mcp-server logout 即可移除已保存的令牌。若要在服务端撤销令牌，请在 Unsplash 控制面板中重新生成应用密钥。

工具

所有工具均使用命名空间 unsplash_*。大多数工具均为只读（标注为 readOnlyHint: true）；例外情况是 unsplash_track_download（用于登记下载事件）以及下面列出的 8 个写入/me 工具，这些工具均标记为非只读，并且需要先通过 OAuth 登录。参数与 Unsplash API 对应；per_page 和统计数据中的 quantity 上限为 30，page 从 1 开始计数。

🔒 = 需要先通过 OAuth 登录（login）。

工具参考

输出格式

工具返回经过精简、节省 token 的 JSON，而非原始 Unsplash 响应：

• 照片 → id、description、width/height、color、blur_hash、urls（raw/full/regular/small/thumb）、photo_page、download_location、photographer，以及可直接使用的 attribution 对象。参见交互示例。
• 用户 → id、username、name、bio、location、profile_url、profile_image、total_photos、total_collections。
• 合集 / 主题 → 标题、说明、数量、页面链接、策展人/所有者，以及精简的 cover_photo。
• 每个结果都包含 rate_limit（limit、remaining）；列表/搜索结果还会包含分页字段。

资源与提示词

除了工具，服务还会提供：

• 资源 — 简明指南，客户端可将其作为上下文引入：

  • unsplash://guides/attribution — 署名、下载追踪、热链和内容安全。
  • unsplash://guides/oauth-setup — 如何登录以使用 8 个写入/me 工具。
  • unsplash://guides/prompts — 针对特定任务，应使用下方的哪些提示词。

• 提示词 — 可供客户端直接展示的现成任务；每个提示词都会展开为一个分步骤的工具调用任务：

  提示词	参数	功能
  find_photo	subject（必填），orientation?	搜索一张照片并附上署名。
  photo_gallery	theme（必填），count?，orientation?，color?	制作一组主题照片（最多 10 张），每张均附上署名。
  topic_spotlight	topic（必填），count?	展示精选主题中的最佳照片。
  photographer_spotlight	username（必填），count?	展示摄影师的个人资料及其最受欢迎的作品。
  platform_pulse	（无）	快速了解 Unsplash 全站统计数据。
  curate_collection 🔒	theme（必填），count?，collection_id?	搜索并根据匹配结果创建（或扩展）一个实际的合集。
  describe_photo 🔒	id（必填），description?，tags?	为你拥有的照片添加描述/标签。
  refresh_profile 🔒	bio?，location?，url?	更新你自己的简介、所在地或作品集 URL。

  🔒 = 需先使用 OAuth 登录。

提示词示例

可直接对应工具的自然语言请求：

• “查找一张日出时雾气弥漫的森林照片，并提供 HTML 署名。”
• “在 Unsplash 上搜索 5 张极简风格的横向工作空间照片。”
• “获取一张随机自然照片并显示署名。”
• “展示 wallpapers 主题中最受欢迎的照片。”
• “本月 Unsplash 全站的下载统计数据是多少？”
• “照片 Dwu85P9SOIk 的摄影师是谁？这张照片有多少次下载？”

署名与合规

每个照片结果都包含一个 attribution 对象，其中有可直接使用的 text 和 html（带有所需的 UTM 参数）。展示或使用照片时，请显示该署名 — 按照指南的要求，这样既能注明摄影师，也能链接回 Unsplash。

实际_使用_照片（嵌入、下载或展示）时，请使用照片的 download_location 调用 unsplash_track_download。每张实际使用的照片都要调用一次 — 绝不能对每个搜索结果都调用一次。服务也会在连接时向 MCP 客户端发送这些说明，提醒模型自动遵循要求。

这是用于单张照片搜索和元数据查询的工具，照片使用时需注明出处 — 不能替代 Unsplash 的核心体验，也不会自动批量下载。请按照 Unsplash API 指南使用。每位用户均受其各自的 Unsplash API 条款约束。

速率限制

Unsplash 会根据应用所属的层级，限制每小时的请求额度：

服务会读取 X-Ratelimit-Limit / X-Ratelimit-Remaining，并在每个结果中将其作为 rate_limit 返回。每小时的额度用尽时，Unsplash 会返回 403（而非 429），且通常不提供 Retry-After；服务会将其作为明确的“每小时速率限制已达到”错误返回，并且不会在当前时段内盲目重试。对于临时的 429/5xx/网络错误，服务 会 使用退避策略重试。

Unsplash 文本的处理方式

照片描述、替代文本、标签、EXIF，以及用户名和个人简介均来自 Unsplash 贡献者——应将其视为不可信的第三方数据，而非指令。服务仅将这些文本作为内容返回，不会将其放在任何特权位置；你的客户端/Agent 也应如此处理：可以显示这些文本，但不要执行其中可能包含的任何指令（以防间接提示词注入）。

隐私与安全

• **无遥测。**此服务不会收集任何信息，也不会向任何人回传数据。它只会使用你提供的密钥联系 api.unsplash.com。无分析，无跟踪。
• **可验证的来源。**每个版本都会通过 GitHub Actions 使用 npm provenance 发布——npm 软件包页面会将每个版本链接到构建该版本的确切提交和工作流运行记录。
• 密钥安全。访问密钥仅从环境中读取，并通过 Authorization: Client-ID 标头发送（绝不会放在 URL 查询字符串中），且会从所有错误输出和日志中脱敏，防止密钥泄漏到粘贴的错误报告中。
• SSRF 防护。unsplash_track_download 只会跟随指向已验证 api.unsplash.com 主机的 download_location URL。
• 如需报告漏洞，请参阅 SECURITY.md。

故障排查

• 启动时显示“Set UNSPLASH_ACCESS_KEY…”——密钥环境变量缺失或为空；请将其添加到客户端配置的 env 区块中。
• Node 版本过旧——此服务需要 Node 20+。请检查 node --version。
• npx 版本过旧——使用 npx -y @hanoak/unsplash-mcp-server@latest 强制获取最新版本，或通过 npx clear-npx-cache 清除缓存。
• 工具未显示——确认配置文件路径和 JSON 有效，然后完全退出并重新打开客户端。
• 403 / 速率限制——Demo 层级每小时允许 50 个请求；请等待每小时额度重置，或申请 Production 访问权限。请参阅速率限制。
• 401 Unauthorized——访问密钥错误或来自错误的应用；请从应用控制面板复制 Access Key（而非 Secret Key）。

常见问题

需要付费的 Unsplash 账户吗？ 不需要。Unsplash API 免费；只需注册一个应用即可获取访问密钥。更高的吞吐量（Production 层级）通过免费审核获得，并非付费方案。

Access Key 和 Secret Key——该用哪个？ 对于 21 个只读工具，只需 Access Key。只有 login（8 个写入/me 工具背后的 OAuth 流程）需要 Secret Key——请参阅OAuth 登录。

它会下载或重新托管图片吗？ 不会。它会返回由 Unsplash 托管的图片 URL（可直接使用热链），绝不会重新托管图片或返回 base64 数据块。unsplash_track_download 只会登记下载事件并返回一个新的 URL。

它可以创建合集、点赞照片或编辑我的个人资料吗？ 可以，完成登录后即可——包括 unsplash_create_collection 等工具，以及 unsplash_update_photo/unsplash_update_my_profile。（目前尚未将点赞照片作为工具提供。）

它能在 Claude 以外的环境中运行吗？ 可以——这是一个标准的 stdio MCP 服务。请参阅客户端设置部分，了解 Claude Code、Cursor、VS Code、Windsurf 和通用 stdio 的设置方法。

要求

• Node.js >= 20（Node 18 已结束生命周期）。
• Unsplash API 访问密钥。

兼容性

路线图

完整详情请见 docs/ROADMAP.md。简而言之：

• v1 (已发布) — 21 个只读工具、署名与下载追踪合规、署名资源，以及 find_photo 提示词。
• v2 (已发布) — 通过 login/logout CLI 和 Unsplash 授权码流程提供 8 个 OAuth 写入/me 端点（个人资料、合集、照片元数据）。
• v3 (当前) — 新增 7 个 MCP 提示词，覆盖所有工具领域（请参阅资源与提示词）。曾考虑在此阶段推出 .mcpb Desktop Extension，但已将其移至未来待定范围——npx 已能在所有受支持的客户端上运行。

变更记录见 CHANGELOG.md；本项目遵循 Semantic Versioning。

贡献

欢迎贡献——请参阅 CONTRIBUTING.md 和我们的行为准则。其中涵盖本地设置、测试套件、使用 MCP Inspector 手动测试工具，以及版本管理/弃用政策。若要报告漏洞，请参阅 SECURITY.md。

联系与社区

由 Hanoak S 维护。获取帮助或提出功能建议的最快方式是提交 Issue——Issue 公开可查，也能帮助整个社区。其他事宜请联系：

如果这个项目对你有帮助，欢迎在 GitHub 上点一个 ⭐——这有助于其他人发现这个 Unsplash MCP 服务。

许可证

MIT © Hanoak S。与 Unsplash 无关联。