🖼️ Unsplash Smart MCP Server

🖼️ Unsplash Smart MCP 服务

让 AI Agent 轻松获得惊艳视觉内容。

一个强大的 FastMCP 服务，可让 AI Agent 借助智能上下文感知和自动署名管理，无缝搜索、推荐并获取来自 Unsplash 的专业图库照片。

🚀 为什么选择此 Unsplash 集成方案

在视觉内容集成领域，我们的 Unsplash Smart MCP 服务凭借以下优势脱颖而出，成为 AI 图像获取的理想解决方案：

• 🧠 针对 AI Agent 优化：专为 Cursor 中的 Claude 等 AI Agent 打造，支持通过自然语言简化图像请求
• 🔍 上下文感知的图像选择：智能理解模糊请求，即使提示词抽象，也能提供相关图像
• ⚡ 高效的单工具设计：通过统一的 stock_photo 工具处理完整图像工作流，避免工具泛滥
• 📊 资源优化：采用 URL 优先的方式，节省带宽和存储空间，同时保持灵活性
• ✅ 自动署名：内置遵循 Unsplash 服务条款的机制，无需开发者费心
• 📁 项目感知型组织：根据项目结构（Next.js、React、Vue 等）智能整理图像
• 🧩 无缝集成：设计注重简化设置，并最大限度兼容现有工作流

✨ 超越同类方案的功能

面向 AI Agent 开发者

• 智能上下文搜索：通过自然语言请求找到理想图像
• 自动选择主题：AI 根据用途描述确定最佳图像主题
• 由意图驱动的结果：获取的不只是匹配关键词，更是符合深层意图的图像
• 无缝集成 Agent：开箱即用，支持 Cursor 中的 Claude 及其他兼容 MCP 的 Agent

面向项目效率

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

面向合规保障

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

🛠️ 安装

前置条件

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

本地安装（推荐）

1. 克隆仓库：

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

2. 安装依赖：

npm install

3. 配置 Cursor MCP 设置：

   • macOS：编辑 ~/.cursor/mcp.json
   • Windows：编辑 %USERPROFILE%\.cursor\mcp.json
   • Linux：编辑 ~/.cursor/mcp.json

4. 添加以下配置：

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

5. 替换：

   • 将 /absolute/path/to/unsplash-smart-mcp-server 替换为克隆仓库的实际路径
   • 将 your_api_key_here 替换为你的 Unsplash API 密钥

6. 保存文件并重启 Cursor。

重要： 与许多 MCP 服务不同，此服务需要直接进行进程管道通信。由于其处理 FastMCP I/O 交互的方式，无法通过 TCP 端口或直接通过 npm 访问。本地安装方式是最可靠的方案。

Cursor CLI 替代方案

如果你更喜欢使用 Cursor 的 CLI：

claude mcp add unsplash npx tsx /path/to/unsplash-smart-mcp-server/src/server.ts --cwd /path/to/unsplash-smart-mcp-server
claude mcp config set unsplash UNSPLASH_ACCESS_KEY=your_api_key_here

将路径和 API 密钥替换为实际值。

通过 Docker 安装（最可靠的方法）

1. 克隆仓库：

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

2. 创建 docker-compose.yml 文件：

services:
  unsplash-mcp:
    build: .
    image: unsplash-mcp-server
    restart: always
    stdin_open: true
    tty: true
    environment:
      - UNSPLASH_ACCESS_KEY=your_api_key_here

3. 构建并启动容器：

docker-compose up -d

4. 配置 Cursor MCP 设置：

   • macOS：编辑 ~/.cursor/mcp.json
   • Windows：编辑 %USERPROFILE%\.cursor\mcp.json
   • Linux：编辑 ~/.cursor/mcp.json

5. 添加以下配置：

{
  "servers": {
    "unsplash": {
      "command": "docker",
      "args": ["exec", "-i", "unsplash-mcp-unsplash-mcp-1", "tsx", "src/server.ts"],
      "env": {}
    }
  }
}

6. 保存文件并重启 Cursor。

此设置将：

• 在 Docker 启动时自动启动服务
• 在服务崩溃时重启服务
• 在后台运行，无需打开终端窗口
• 为 Cursor 提供可靠的连接

通过 Smithery 部署（云端部署）

如果你更喜欢云端部署，可以使用 Smithery：

1. 通过 Smithery 在 Cursor 中安装服务：

npx @smithery/cli install @drumnation/unsplash-smart-mcp-server --client cursor --key your_api_key_here

2. 你也可以登录 Smithery.ai，通过其 Web 界面进行部署。

Windows 用户注意： Smithery 部署包含针对 Windows 兼容性的特殊处理。

如需详细说明和故障排查，请参阅 Smithery 部署指南。

🧩 与 AI Agent 集成

在 Cursor 中使用 Claude 的分步指南

我们的 Unsplash Smart MCP Server 旨在让通过 AI Agent 获取图片变得轻松直观：

1. 发起请求：只需用自然语言向 Claude 请求图片
2. AI 解读：Claude 理解你的需求，并使用优化后的参数调用 stock_photo 工具
3. 智能选择图片：服务理解上下文并查找最相关的图片
4. 展示选项：Claude 向你展示最佳匹配结果和下载命令
5. 无缝下载：执行建议的命令，将图片放到你需要的位置
6. 自动署名：所有署名数据都会被保存，并可随时访问

此流程省去了传统工作流中的以下步骤：

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

适用于 AI Agent 的提示词示例

在 Cursor 中使用自然语言提示词向 Claude 请求图片，例如：

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

🪟 Windows 兼容性

如果你在 Windows 上运行 MCP 服务时，遇到 Cursor 中的“Client closed”错误，请按以下特殊配置步骤操作：

Windows 专用 MCP 配置

在 .cursor 目录中创建名为 mcp.json 的文件（通常位于 %USERPROFILE%\.cursor\mcp.json），并使用以下任一配置：

选项 1：直接执行 Node（推荐）

{
  "mcpServers": {
    "stock_photo": {
      "command": "node",
      "args": ["./node_modules/.bin/tsx", "path/to/unsplash-mcp/src/server.ts"],
      "disabled": false,
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_api_key_here"
      },
      "shell": false
    }
  }
}

选项 2：PowerShell 方案

{
  "mcpServers": {
    "stock_photo": {
      "command": "powershell",
      "args": ["-Command", "npx tsx path/to/unsplash-mcp/src/server.ts"],
      "disabled": false,
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_api_key_here"
      }
    }
  }
}

有关 Windows 兼容性的完整文档，请参阅 Windows 兼容性指南。

🛠️ API 参考

以 URL 为先：明智之选

我们的架构采用以 URL 为先的方法，而非直接嵌入图像，原因有以下几点：

1. 存储效率：避免 AI Agent 在上下文中存储不必要的大型二进制数据
2. 节省带宽：减少服务间的数据传输，提升响应速度
3. 灵活选择位置：开发者可以在需要的位置下载图像
4. 权限管理：避免在受限环境中遇到文件系统权限问题
5. 工作流集成：与现有开发管道无缝集成

这一策略使 AI Agent 能够根据项目上下文智能地建议最佳下载位置，而不受自身环境限制。

减少工具刷屏和 API 调用

与其他需要多次调用工具来搜索、筛选、下载和标注图像的解决方案不同，我们的服务：

• 将整个图像工作流整合到单个 stock_photo 工具中
• 优化结果获取：预先请求更多图像，以便更好地筛选
• 消除 Agent 与服务之间的来回交互
• 通过简化请求和响应格式，减少 Agent 的 Token 使用量

这种设计显著减少了 API 调用和工具调用次数，从而加快结果获取速度并降低运营成本。

🔄 自动标注与合规

Unsplash 服务条款：轻松合规

使用 Unsplash 图像必须遵守其服务条款。我们的服务会自动处理：

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

使用我们的 Unsplash Smart MCP Server，即可自动满足 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 Server 可无缝集成到您的开发工作流中：

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 Server	替代方案
AI Agent 集成	✅ 专为 AI Agent 工作流打造	❌ 通常需要手动设置参数
上下文感知	✅ 能智能理解模糊请求	❌ 依赖精确的关键词匹配
工具效率	✅ 单个工具即可处理整个工作流	❌ 通常需要使用多个独立工具
署名管理	✅ 提供包含多种格式的完整系统	❌ 手动跟踪或仅提供基础文本输出
项目组织	✅ 能识别框架的文件夹结构	❌ 将文件通用地下载到单一位置
安装复杂度	✅ 一行命令即可完成	❌ 通常需要多个配置步骤
响应格式	✅ 针对 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	图片的用途（例如，主视觉、背景）	-
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	用于整理图片的类别（例如，主视觉、背景）	-
downloadMode	string	下载图片或返回 URL	urls_only

get_attributions

参数	类型	说明	默认值
format	string	输出格式（json、html、react）	json
projectPath	string	将署名筛选到特定项目路径	-
outputPath	string	署名文件的保存位置	-

🔧 故障排除

常见问题和解决方案

问题	解决方案
连接被拒绝	确保服务在配置的端口上运行
身份验证错误	确认已正确设置 Unsplash API 密钥
未找到图片	尝试更宽泛的搜索词，或检查搜索查询
下载权限问题	使用 downloadMode: 'urls_only' 和手动下载命令
Docker 容器提前退出	确保在 Dockerfile 中使用 CMD ["npm", "start"]，而不是直接使用 tsx 运行 TypeScript 文件。这可确保服务在 Docker 环境中持续运行。
超时错误	默认 MCP 超时时间为 60 秒，对于下载较大的图片或处理多张图片可能不够。对于图片较多的操作：1）每次请求处理较少的图片；2）使用较小的图片尺寸；3）考虑使用 urls_only 模式而非自动下载；4）检查网络连接
未找到署名信息	确认图片是通过 MCP 服务下载的
未处理的 MCP 错误	如果看到 "McpError: MCP error -32001: Request timed out" 错误，说明请求可能耗时过长。请将操作拆分为较小的步骤，或仅使用 URL 的方式

🤝 参与贡献

欢迎贡献！欢迎提交 Pull Request。

开发工作流

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

🗺️ 路线图

以下是我们为后续版本规划的内容：

• 图片编辑功能：基本的调整尺寸、裁剪和调整工具
• 高级搜索筛选器：更精细地控制图片选择
• 批量处理：高效处理多个图片请求
• 自定义合集：为项目保存和管理图片组
• 团队协作：共享署名信息和图片合集
• 使用情况分析：跟踪图片在各个项目中的使用情况
• 更多图片来源：集成其他图库服务商
• 改进超时处理：增强超时配置和恢复机制

📄 许可证

MIT 许可证

📚 署名要求

使用 Unsplash 图片时，必须遵守 Unsplash 许可证：

• 无需署名，但我们对此表示感谢
• 不得出售未经修改的照片副本
• 不得汇编 Unsplash 照片来创建竞争性服务

我们的服务内置署名系统，可让你轻松为摄影师提供适当署名。

📞 联系方式

如有问题或疑问，请在 GitHub 上提交问题。

🧰 开发和测试

在本地运行服务

# Clone the repository
git clone https://github.com/drumnation/unsplash-smart-mcp-server.git
cd unsplash-smart-mcp-server

# Install dependencies
npm install

# Set up your environment variables
cp .env.example .env
# Edit .env to add your UNSPLASH_ACCESS_KEY

# Start the development server
npm run dev

测试

此软件包包含全面的测试套件：

# Run core tests
npm test

# Run all tests and get a summary report
npm run test:all

测试套件包括：

• 单元测试和集成测试
• 手动工具测试
• Docker 容器测试
• Smithery.ai 集成测试

有关测试的详细信息，请参阅 docs/testing.md。

---

每次都为你的 AI Agent 提供完美图片。
为开发者和 AI 爱好者倾心打造。