🖼️ Unsplash Smart MCP 服务器

让你的 AI 代理拥有惊艳的视觉效果，无需任何麻烦。

一个强大的 FastMCP 服务器，使 AI 代理能够无缝地搜索、推荐和提供来自 Unsplash 的专业图库照片，具有智能的上下文感知和自动署名管理。

🚀 为什么选择这个 Unsplash 集成

在视觉内容集成的领域中，我们的 Unsplash Smart MCP 服务器是 AI 驱动图像获取的最终解决方案：

• 🧠 AI 代理优化：专为 Cursor 中的 Claude 等 AI 代理构建，通过自然语言简化图像请求
• 🔍 上下文感知图像选择：智能地解释模糊的请求，即使从抽象的提示中也能提供相关的图像
• ⚡ 单一工具效率：通过统一的 stock_photo 工具处理整个图像工作流程，消除工具垃圾
• 📊 资源优化：URL 优先的方法节省带宽和存储空间，同时保持灵活性
• ✅ 自动署名：内置符合 Unsplash 的服务条款，无需开发者付出任何努力
• 📁 项目感知组织：根据您的项目结构（Next.js、React、Vue 等）智能地组织图像
• 🧩 无缝集成：设计用于最小的设置和与您现有工作流程的最大兼容性

✨ 无与伦比的功能

适用于 AI 代理开发者

• 智能上下文搜索：通过自然语言请求找到完美的图像
• 自动主题选择：AI 根据您的目的描述确定最佳图像主题
• 意图驱动的结果：获取不仅匹配关键字，而且匹配底层意图的图像
• 无缝代理集成：与 Cursor 中的 Claude 和其他 MCP 兼容的代理开箱即用

适用于项目效率

• 两步工作流程：获取用于控制下载的 URL，避免权限问题和不必要的存储
• 项目感知文件管理：根据框架约定自动组织图像
• 智能目录创建：根据您的项目类型创建适当的文件夹结构
• 渐进式增强：适用于任何项目规模，从快速原型到企业应用程序

适用于合规性安心

• 完整的署名管理：
  • 本地署名数据库跟踪所有图像使用情况
  • 自动将摄影师元数据嵌入图像（EXIF、IPTC、XMP）
  • 一键生成多种格式的署名页面
  • 用于署名数据的综合 API

🛠️ 安装

前提条件

• Node.js 18.x 或更高版本
• 一个 Unsplash API 访问密钥（在此处获取）

通过 Cursor（推荐）

1. 在 Cursor 中安装 MCP 服务器：

claude mcp add unsplash https://github.com/drumnation/unsplash-smart-mcp-server.git

2. 设置您的 Unsplash API 密钥：

claude mcp config set unsplash UNSPLASH_ACCESS_KEY=your_api_key_here

在 Cursor 中手动配置

如果 claude mcp add 命令对您不起作用，您可以在 Cursor 设置中手动配置 MCP 服务器：

1. 找到您的 Cursor MCP 配置文件：

   • macOS: ~/.cursor/mcp.json
   • Windows: %USERPROFILE%\.cursor\mcp.json
   • Linux: ~/.cursor/mcp.json

2. 将 Unsplash MCP 服务器配置添加到文件中的 servers 对象：

{
  "servers": {
    "unsplash": {
      "command": "tsx",
      "args": ["/path/to/unsplash-smart-mcp-server/src/server.ts"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_api_key_here"
      }
    }
  }
}

将 /path/to/unsplash-smart-mcp-server 替换为您克隆存储库的实际路径，并将 your_api_key_here 替换为您的实际 Unsplash API 密钥。

3. 保存文件并重新启动 Cursor 以使更改生效。

4. 通过在 Cursor 中询问 Claude 来验证集成：

Find me an image of a mountain landscape

Claude 应该通过使用 Unsplash MCP 服务器来搜索和建议山地景观图像来响应。

通过 Smithery（云部署）

您还可以通过 Smithery 部署此 MCP 服务器以进行基于云的访问：

1. 访问 Smithery.ai 并登录
2. 单击“添加服务器”并选择“从 GitHub 导入”
3. 输入存储库 URL：https://github.com/drumnation/unsplash-smart-mcp-server.git
4. 填写表格，内容如下：
   • ID: @drumnation/unsplash-smart-mcp-server
   • 基本目录：.（只是一个句点）
   • 仅限本地：未选中（不需要）
5. 单击“创建”以部署服务器
6. 在 Smithery 界面中配置您的 Unsplash API 密钥

通过 Docker

您还可以使用 Docker 运行服务器：

1. 克隆存储库：

git clone https://github.com/drumnation/unsplash-smart-mcp-server.git
cd unsplash-smart-mcp-server

2. 构建 Docker 镜像：

docker build -t unsplash-mcp-server .

3. 使用您的 Unsplash API 密钥运行容器：

docker run -i --rm -e UNSPLASH_ACCESS_KEY=your_api_key_here unsplash-mcp-server

4. 要与 Cursor 或其他 MCP 客户端一起使用，请将以下内容添加到您的 MCP 配置中：

{
  "servers": {
    "unsplash": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "UNSPLASH_ACCESS_KEY=your_api_key_here", "unsplash-mcp-server"]
    }
  }
}

手动安装

1. 克隆存储库：

git clone https://github.com/drumnation/unsplash-smart-mcp-server.git
cd unsplash-smart-mcp-server

2. 安装依赖项：

npm install

3. 创建一个包含您的 Unsplash API 密钥的 .env 文件：

UNSPLASH_ACCESS_KEY=your_api_key_here

4. 构建并启动服务器：

npm run build
npm start

🧩 与 AI 代理集成

Claude in Cursor 的分步指南

我们的 Unsplash Smart MCP 服务器旨在使通过 AI 代理获取图像变得轻松直观：

1. 发起请求：只需用自然语言向 Claude 询问图像
2. AI 解释：Claude 了解您的需求并使用优化的参数调用 stock_photo 工具
3. 智能图像选择：服务器解释上下文并找到最相关的图像
4. 选项呈现：Claude 向您展示最佳匹配项和下载命令
5. 无缝下载：执行建议的命令以将图像放置在您需要的确切位置
6. 自动署名：所有署名数据都已存储，可以随时访问

此过程消除了以下传统工作流程：

1. 手动搜索 Unsplash
2. 滚动浏览数百个结果
3. 将图像下载到随机位置
4. 将文件移动到正确的项目文件夹
5. 手动跟踪署名数据
6. 创建署名页面

AI 代理的示例提示

使用如下自然语言提示向 Cursor 中的 Claude 询问图像：

"Find a professional image for a tech startup landing page hero section"

"I need a photo that represents innovation and creativity for my presentation"

"Get me a picture of a diverse team collaborating in a modern office environment"

"Find an abstract background that represents data and analytics"

"I need a photo of someone coding or debugging software for a blog post"

"Find an image that conveys artificial intelligence ethics for my research paper"

"Get a minimalist product photo with a white background for an e-commerce site"

"Find a landscape photo that evokes a sense of possibility and exploration"

"I need a photo showing user experience design for my UX portfolio"

"Find an image representing sustainable technology for an environmental tech article"

URL 优先方法：明智的选择

我们的架构使用 URL 优先方法而不是直接图像嵌入，原因如下：

1. 存储效率：防止 AI 代理不必要地在其上下文中存储大型二进制数据
2. 带宽节省：减少服务之间的数据传输，从而缩短响应时间
3. 放置灵活性：允许开发人员将图像下载到他们需要的确切位置
4. 权限管理：避免受限环境中的文件系统权限问题
5. 工作流程集成：与现有开发管道无缝集成

此策略使 AI 代理能够根据项目上下文智能地建议最佳下载位置，而不会受到自身环境限制的约束。

最小化工具垃圾和 API 调用

与其他需要多次工具调用才能搜索、过滤、下载和署名图像的解决方案不同，我们的服务器：

• 将整个图像工作流程统一到一个 stock_photo 工具中
• 通过预先请求更多图像来优化结果检索，从而实现更好的过滤
• 消除代理和服务之间的乒乓交互
• 通过简化请求和响应格式来减少代理令牌使用量

这种设计显着减少了 API 调用和工具调用的数量，从而加快了结果并降低了运营成本。

🔄 自动署名和合规性

Unsplash 服务条款：轻松合规

使用 Unsplash 中的图像需要遵守其 服务条款。 我们的服务器会自动处理此问题：

1. 署名数据捕获：每次图像下载都会自动存储摄影师信息
2. 元数据嵌入：摄影师详细信息直接嵌入到图像文件中
3. 署名数据库：本地数据库维护所有图像使用情况的记录
4. 署名生成器：内置工具创建 HTML 和 React 署名组件
5. API 访问：简单的端点可检索任何项目的署名数据

通过使用我们的 Unsplash Smart MCP 服务器，您可以自动符合 Unsplash 的要求，而无需任何额外的工作。

署名管理系统

该服务器包括一个全面的署名管理系统：

// Retrieve attribution data for your project
const attributions = await fetch('http://localhost:3000/api/unsplash', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    method: 'get_attributions',
    params: {
      format: 'json',  // Options: json, html, react
      projectPath: '/path/to/your/project'
    }
  })
}).then(res => res.json());

// attributions contains complete data about every image used

该 API 可以生成三种类型的署名文件：

1. JSON：用于自定义实现的结构化数据
2. HTML：用于网站页脚或鸣谢部分的即用型 HTML 页面
3. React：用于现代 Web 应用程序的嵌入式 React 组件

💼 开发者工作流程集成

真实世界的用例

我们的 Unsplash Smart MCP 服务器无缝集成到您的开发工作流程中：

UI 开发

• 使用相关的占位符图像立即填充模型
• 跨组件保持一致的图像尺寸
• 在您的项目结构中以逻辑方式组织图像

文档

• 使用解释性视觉效果增强技术文档
• 创建具有视觉吸引力的教程和指南
• 维护所有视觉资产的正确署名

内容创建

• 快速查找博客文章和文章的图像
• 为社交媒体内容生成视觉效果
• 访问产品营销的一致图像

应用程序开发

• 使用产品图像填充电子商务网站
• 创建视觉丰富的用户体验
• 为不同的部分维护单独的图像集合

框架特定的组织

图像会根据您的项目类型自动组织：

框架	默认图像路径	备用路径
Next.js	/public/images/	/public/assets/images/
React	/src/assets/images/	/assets/images/
Vue	/src/assets/images/	/public/images/
Angular	/src/assets/images/	/assets/images/
Generic	/assets/images/	~/Downloads/stock-photos/

🥇 竞争差异化

为什么选择我们的 Unsplash 集成？

功能	Unsplash Smart MCP 服务器	替代方案
AI 代理集成	✅ 专为 AI 代理工作流程构建	❌ 通常需要手动参数设置
上下文感知	✅ 智能地解释模糊的请求	❌ 依赖于精确的关键字匹配
工具效率	✅ 单个工具处理整个工作流程	❌ 通常需要多个单独的工具
署名管理	✅ 具有多种格式的综合系统	❌ 手动跟踪或基本文本输出
项目组织	✅ 框架感知的文件夹结构	❌ 通用下载到单个位置
安装复杂性	✅ 简单的一行命令	❌ 通常需要多个配置步骤
响应格式	✅ 针对 AI 优化，具有相关上下文	❌ 需要进一步处理的通用 JSON
下载灵活性	✅ URL 优先，具有智能建议	❌ 直接下载或仅 URL

⚙️ 配置

环境变量

变量	描述	默认值
UNSPLASH_ACCESS_KEY	您的 Unsplash API 访问密钥	-
PORT	服务器侦听的端口	3000
HOST	服务器的主机	localhost
ATTRIBUTION_DB_PATH	存储署名数据库的路径	~/.unsplash-mcp

工具参数

stock_photo

参数	类型	描述	默认值
query	string	要搜索的内容（如果未指定，AI 将选择）	-
purpose	string	图像将在何处使用（例如，hero，background）	-
count	number	要返回的图像数量	1
orientation	string	首选方向（any，landscape，portrait，square）	any
width	number	目标宽度（以像素为单位）	-
height	number	目标高度（以像素为单位）	-
minWidth	number	用于过滤结果的最小宽度	-
minHeight	number	用于过滤结果的最小高度	-
outputDir	string	保存照片的目录	~/Downloads/stock-photos
projectType	string	用于文件夹结构的项目类型（next，react，vue，angular）	-
category	string	用于组织图像的类别（例如，heroes，backgrounds）	-
downloadMode	string	是下载图像还是返回 URL	urls_only

get_attributions

参数	类型	描述	默认值
format	string	输出格式（json，html，react）	json
projectPath	string	将署名过滤到特定的项目路径	-
outputPath	string	保存署名文件的位置	-

🔧 故障排除

常见问题和解决方案

问题	解决方案
连接被拒绝	确保服务器正在配置的端口上运行
身份验证错误	验证您的 Unsplash API 密钥是否已正确设置
未找到图像	尝试更广泛的搜索词或检查您的搜索查询
下载权限问题	使用 downloadMode: 'urls_only' 和手动下载命令
超时错误	默认的 MCP 超时时间为 60 秒，这可能不足以用于下载较大的图像或处理多个图像。 对于图像繁重的操作：1) 每次请求处理较少的图像，2) 使用较小的图像尺寸，3) 考虑使用 urls_only 模式而不是自动下载，4) 检查网络连接
未找到署名	验证图像是否通过 MCP 服务器下载
未处理的 MCP 错误	如果您看到 "McpError: MCP error -32001: Request timed out" 错误，则您的请求可能花费的时间太长。 将其分解为较小的操作或使用仅 URL 的方法

🤝 贡献

欢迎贡献！ 请随时提交拉取请求。

开发工作流程

1. 克隆存储库
2. 使用 npm install 安装依赖项
3. 创建一个包含您的 Unsplash API 密钥的 .env 文件
4. 使用 npm run dev 在开发模式下运行
5. 使用 npm test 运行测试

🗺️ 路线图

以下是我们计划在未来版本中发布的内容：

• 图像编辑功能：基本调整大小、裁剪和调整工具
• 高级搜索过滤器：对图像选择进行更精细的控制
• 批量处理：高效处理多个图像请求
• 自定义集合：保存和管理项目的图像组
• 团队协作：共享署名和图像集合
• 使用情况分析：跟踪跨项目图像的使用情况
• 其他图像来源：与其他图库照片提供商集成
• 改进的超时处理：增强的超时配置和恢复机制

📄 许可证

MIT 许可证

📚 署名要求

使用 Unsplash 中的图像时，您必须遵守 Unsplash 许可证：

• 不需要署名，但表示感谢
• 您不能出售照片的未经修改的副本
• 您不能编译来自 Unsplash 的照片来创建竞争服务

我们的服务器的署名系统使您可以轻松地为摄影师提供适当的署名。

📞 联系方式

如有问题或疑问，请在 GitHub 上打开一个问题。

---

<p align="center"> <strong>每次都让您的 AI 代理拥有完美的图像。</strong><br> 用 ❤️ 为开发者和 AI 爱好者构建。 </p>