unsplash-mcp-server

想象一下，你正在设计一份演示文稿，需要一张“未来主义建筑”的高质量图片。你不需要离开聊天界面，也不用打开浏览器去Unsplash上搜索。你只需要告诉你的AI助手一句：“帮我找一张竖版的、蓝色调的未来主义建筑照片。”几秒钟内，AI就会返回几张精美的、可直接使用的图片链接。这正是unsplash-mcp-server带来的体验。

unsplash-mcp-server是一个模型上下文协议服务器，它将全球最大的高品质免费图片库Unsplash的搜索能力，无缝接入到你的AI客户端中。通过这个简洁而强大的工具，你的AI可以直接为你搜索和推荐数百万张免版权的专业摄影作品。

项目基本信息

一、项目介绍

unsplash-mcp-server的核心功能非常专注：它只提供了一项工具，但这一工具足以满足几乎所有图片搜索需求。这个工具就是search_photos。

通过search_photos，你的AI可以将你的自然语言需求，转化为精确的Unsplash图片搜索。你可以指定搜索的关键词，也可以设置多个筛选条件，包括图片的色系、方向以及排序方式。服务器会将搜索到的图片列表返回给AI，其中包含了每张图片的预览图、摄影师信息、下载链接等丰富元数据。

整个项目完全使用Python编写，结构极其清晰。它的安装和使用方式也非常灵活，既可以通过uv Python包管理器直接运行，也支持通过Docker容器化部署。对于追求极致便捷的用户，它还提供了通过Smithery平台一键安装到Cursor、Windsurf等主流IDE的功能。

二、核心优势

聚焦核心需求，体验纯粹：与那些功能复杂的“瑞士军刀”式服务器不同，unsplash-mcp-server只做一件事——搜索Unsplash图片，并且做得非常好。它的简洁性意味着更少的出错可能性和更低的认知负担。你和你的AI都知道，当需要图片时，就应该调用这个工具。

利用全球最大的免费图库：Unsplash是无数设计师、博主和内容创作者的图片首选来源。所有图片均可免费用于商业和非商业项目，无需署名（虽然署名是礼貌的）。通过这个服务器，你的AI可以直接访问这个拥有数百万高质量图片的宝库。

丰富的筛选能力：它不仅仅是一个关键词搜索。你可以按orientation（方向）精确寻找横图、竖图或方图，按color（色系）找到符合品牌色调的图片，还可以自定义每页返回的数量（per_page，默认10，最大30）。这种精细化的搜索能力，让你能非常精确地找到最符合需求的视觉素材。

多种便捷的安装路径：项目考虑到了不同用户的需求。对于普通用户，通过Smithery可以一键安装到IDE。对于喜欢手动控制的用户，可以使用uv命令在终端中安装和运行。对于需要集成到复杂环境的用户，Docker镜像提供了高度一致性。这种灵活性大大降低了使用门槛。

三、适用场景

场景一：内容创作与文章配图。无论你是在写博客、做微信公众号文章，还是制作PPT，都可以让AI帮你寻找配图。“帮我找一张关于‘团队协作’的图片，要求横图，暖色调。” AI会立刻返回几张合适的Unsplash图片链接，供你选择使用。

场景二：设计灵感搜集。如果你是设计师或艺术指导，可以在对话中快速搜集灵感。“请搜索关键词‘极简主义海报’，方向选方图，找5张最受欢迎的。” 你可以快速浏览图片，而不必在Unsplash的搜索页面间来回切换。

场景三：产品与UI设计原型。在设计网站或应用界面时，经常需要占位图片来演示效果。你可以让AI：“找一张高质量的‘笔记本电脑办公’的场景图，竖版，用来做登录页的背景。” 这比自己去图库中翻找要高效得多。

场景四：自动化为项目生成配图集。结合自动化脚本，你可以让程序定期运行这个服务器，为你的项目自动搜集一批主题相关的图片。例如，一个每日更新的“科技新闻”简报，可以每天自动搜索“technology”关键词并随机选择一张作为头图。

场景五：快速演示与原型验证。当你在产品演示或向客户提案时，需要快速生成一些视觉素材来支撑你的想法。通过在对话中实时搜索和展示图片，你可以让演示文稿或原型看起来更加专业和完整，提升说服力。

四、安装教程

使用unsplash-mcp-server前，你需要一个Unsplash API访问密钥。获取过程完全免费。

第一步：获取Unsplash Access Key

1. 访问 Unsplash 开发者平台，注册或登录你的Unsplash账号。
2. 点击“Your apps”，然后点击“New Application”创建一个新应用。
3. 填写应用名称等基本信息（可随意填写），同意开发者条款后提交。
4. 创建成功后，在应用详情页面你会看到一个 Access Key。这是一串字符，请复制并妥善保存。

第二步：选择一种方式安装服务器

这个服务器有多种安装方式。这里我们推荐使用uv直接运行，这是最干净、最快速的方式。

首先，确保你的系统安装了Python 3.8或更高版本。然后，安装uv包管理器：

macOS 或 Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

第三步：配置你的MCP客户端

我们以Claude Desktop为例。找到其配置文件：

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

使用文本编辑器打开该文件，添加以下配置。请务必将YOUR_ACCESS_KEY_HERE替换为你的Unsplash Access Key。

{
  "mcpServers": {
    "unsplash": {
      "command": "npx",
      "args": ["-y", "@hellokaton/unsplash-mcp-server"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "YOUR_ACCESS_KEY_HERE"
      }
    }
  }
}

注意： 如果你更喜欢使用uv运行本地克隆的版本，配置会稍有不同，但使用npx运行官方包是最简单的。

第四步：重启并验证

保存配置文件，然后完全退出你的MCP客户端并重新启动。在新的对话中，尝试提问：“帮我搜索5张关于‘海洋’的图片，方向为横图。”

如果配置成功，AI会调用search_photos工具，并返回一个包含图片链接、描述和摄影师信息的列表。你可以直接点击链接查看图片。

五、使用示例

配置完成后，你就可以用非常自然的语言指令，让AI帮你搜索Unsplash上数百万计的图片了。

示例一：基础关键词搜索

你问：“帮我找一些关于‘咖啡’的高清图片，要竖版的。”

AI会调用search_photos，设置query: "coffee", orientation: "squarish"（竖版对应的参数值可能为squarish或portrait，具体取决于API映射），并返回结果。

示例二：按色系和方向搜索

你问：“我需要一张‘绿色’调、横版、适合做网站banner的‘自然风景’图片。”

AI会构建一个精确的搜索：query: "nature landscape", color: "green", orientation: "landscape"。

示例三：查找最受欢迎的某类图片

你问：“请搜索关键词‘科幻城市’，按照受欢迎程度排序，只给我前3张。”

AI会使用query: "cyberpunk city"，并可以设置order_by等相关参数（具体支持排序方式请参考API文档）。

示例四：一次性获取多张图片用于筛选

你问：“帮我搜一下‘宠物狗’，一次返回20张图片，我一并看看。”

AI会设置per_page: 20，然后返回一个包含20个结果的列表供你选择。

六、常见问题

问题一：AI提示“无法搜索图片”，或者返回结果为空。

解决方案：首先，请检查你的Unsplash Access Key是否正确填写在配置文件中，并且没有过期。Unsplash的API密钥是长期有效的。其次，确认你的搜索关键词是否为英文。Unsplash API对中文关键词的支持可能不理想，建议使用英文词进行搜索。例如，搜索“cat”而不是“猫”。最后，检查网络连接，确保能够正常访问Unsplash的API服务。

问题二：我想搜索的图片方向（如“竖图”）似乎不生效。

解决方案：Unsplash API官方支持的orientation参数值通常为landscape（横图）、portrait（竖图）和squarish（方图）。确保你的AI或你在提示词中使用了正确的值。如果你的AI使用了其他词汇，它可能无法正确映射。你可以手动指导AI：“请使用orientation参数为'portrait'来搜索竖图。”

问题三：返回的图片链接我无法直接使用，或者要求我署名。

解决方案：Unsplash上的图片遵循其自身许可协议，通常允许免费商业使用，无需署名，但官方建议署名以感谢摄影师。服务器返回的链接通常是Unsplash的预览或下载链接，直接可用于网页或演示文稿。如果你需要更高分辨率的原图或遵守特定署名要求，请点击链接进入Unsplash官网页面查看具体说明。

问题四：per_page最大只能设置30吗？

解决方案：是的，根据Unsplash API的限制，单次请求最多只能返回30张图片。这是API本身的设计，为了保护服务器资源和保证响应速度。如果你需要更多结果，可以调整关键词进行更精确的搜索，或者进行分页请求（如果服务器支持）。

问题五：这个服务器需要付费吗？

解决方案：项目本身完全免费且开源。Unsplash API对于合理的调用量也是免费的。但Unsplash有权对滥用行为进行限制。对于个人使用和常规软件开发，完全不用担心费用问题。请避免在极短时间内发送大量自动请求。

七、总结

unsplash-mcp-server是一个教科书级别的“小而美”项目。它精准地切入了一个高频需求——图片搜索，并利用Unsplash这个顶级图库，将能力以最标准、最简洁的MCP工具形式提供给AI客户端。

它的最大魅力在于其单一职责和开箱即用。没有复杂的配置，没有令人困惑的多余功能。你配置好API密钥，就能立刻让AI为你的各种创作场景寻找高质量的视觉素材。它的存在，让AI从一个纯文本工具，进化成了也能理解和推荐视觉内容的助理。

对于内容创作者、设计师、产品经理，或者任何需要经常为文档、演示、网页寻找配图的人，这个工具都能显著提升效率。它省去了在AI和Unsplash网站之间来回切换和复制粘贴的麻烦，让灵感到素材的距离缩短到一句对话之内。

如果你经常为找图而烦恼，我强烈建议你立即尝试unsplash-mcp-server。它会让你感叹：“原来AI帮忙找图，可以这么简单。”