Unsplash Smart MCP Server (unsplash-smart-mcp-server)

](https://mseep.ai/app/drumnation-unsplash-smart-mcp-server)

🖼️ Unsplash智能MCP服务器

为您的AI代理提供令人惊叹的视觉效果，零麻烦。

强大的FastMCP服务器，使AI代理能够无缝搜索、推荐和交付来自Unsplash的专业股票照片，并具有智能上下文感知和自动归因管理功能。

](https://smithery.ai/server/@drumnation/unsplash-smart-mcp-server) ](https://www.npmjs.com/package/@drumnation/unsplash-smart-mcp-server)

🚀 为什么选择这种Unsplash集成

在视觉内容集成领域，我们的Unsplash Smart MCP服务器脱颖而出，成为 最终解决方案 对于人工智能驱动的图像采集：

• 🧠 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访问密钥(在这里买一个)

本地安装（推荐）

1. 克隆存储库：

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

1. 安装依赖项：

npm install

1. 配置光标MCP设置：

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

1. 添加以下配置：

{
  "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"
      }
    }
  }
}

1. 替换：

- /absolute/path/to/unsplash-smart-mcp-server 使用克隆存储库的实际路径 - your_api_key_here 使用Unsplash API密钥

1. 保存文件并重新启动Cursor。

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

游标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

1. 创建一个 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

1. 构建并启动容器：

docker-compose up -d

1. 配置光标MCP设置：

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

1. 添加以下配置：

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

1. 保存文件并重新启动Cursor。

此设置将：

• Docker启动时自动启动服务器
• 如果服务器崩溃，请重新启动服务器
• 在后台运行，无需终端窗口
• 提供与Cursor的可靠连接

Via Smithery（云部署）

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

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

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

1. 或者，您可以登录 Smithery.ai 并通过他们的网络界面进行部署。

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

有关详细说明和故障排除，请参阅 Smithery部署指南.

🧩 与AI代理集成

Cursor中Claude的分步指南

我们的Unsplash Smart MCP服务器旨在通过AI代理轻松直观地进行图像采集：

1. 发起请求：只需向克劳德索要一张自然语言的图片
2. AI解读：克劳德了解您的需求，并致电 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"

🪟 Windows兼容性

如果您使用的是Windows，在Cursor中运行MCP服务器时遇到“客户端关闭”错误，请按照以下特殊配置步骤操作：

Windows特定的MCP配置

创建一个名为的文件 mcp.json 在你的 .cursor 目录（通常位于 %USERPROFILE%\.cursor\mcp.json)使用以下配置之一：

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

{
  "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代理在其上下文中不必要地存储大型二进制数据
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页面
3. 反应：现代web应用程序的嵌入式React组件

💼 开发人员工作流集成

真实世界用例

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

前端开发

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

文档

• 用解释性视觉效果增强技术文档
• 创建视觉上吸引人的教程和指南
• 为所有视觉资产保持适当的归属

内容创建

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

应用开发

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

框架特定组织

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

🥇 竞争差别化

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

⚙️ 配置

环境变量

刀具参数

库存_照片

获取分配

🔧 故障排除

常见问题及解决方法

🤝 贡献

欢迎投稿！请随时提交拉取请求。

开发工作流程

1. 克隆仓库
2. 安装依赖项 npm install
3. 创建一个 .env 使用Unsplash API密钥文件
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.

______________________________________________________________________

Empower your AI agents with the perfect images, every time.

Built with ❤️ for developers and AI enthusiasts.