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

MCP开发工具

提供方 drumnation · 包名 @smithery/cli

开发工具 stdio · 本地进程 无需鉴权 社区 / 第三方 ClaudeCursor
查看接入方式

一个为AI代理提供无缝搜索、推荐和交付Unsplash专业库存照片的智能服务器,具有上下文感知和自动归属管理功能。

一句话选型结论

按资料字段整理

Unsplash Smart MCP Server (unsplash-smart-mcp-server) 属于开发工具类 MCP 服务器,stdio · 本地进程,无需鉴权,可直接接入 Claude、Cursor,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类开发工具 传输方式stdio · 本地进程 鉴权无需鉴权 部署方式本地部署
GitHub 星标 60 仓库热度,无公开仓库时显示未标注
工具数 2 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

开发工具
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量2暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

AI图片搜索TypeScript本地部署自动归属管理上下文感知Unsplash集成开发工具

安装与配置

stdio · 本地进程 无需鉴权
客户端在本机拉起子进程,数据不出本机
npx @smithery/cli install @drumnation/unsplash-smart-mcp-server --client cursor --key your_api_key_here

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 2 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
代码与仓库操作

在对话里直接查代码、提 issue、走 PR,省掉来回切工具。

本地命令与脚本

把构建、测试、格式化这类重复命令交给模型执行。

接口联调与测试

让模型调你的接口、跑一遍用例,快速定位问题。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 2 个工具,职责相对集中,接入后不容易误操作。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude、Cursor,换客户端不用重新研究配置。
  • 资料标注无需鉴权,装好就能连。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在开发工具场景里让模型直接调用外部能力的人。
  • 已经在用 Claude、Cursor 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Unsplash Smart MCP Server (unsplash-smart-mcp-server)当前 2 stdio · 本地进程 本地部署 有 2026-05-17
Git 838e2ec1 12 stdio · 本地进程 本地部署 有 2026-05-17
Markitdown MCP 2c653a5f 1 stdio · 本地进程 本地部署 有 2026-05-17
JavaGuide 未标注 stdio · 本地进程 本地部署 有 2026-04-11
awesome-claude-skills 未标注 stdio · 本地进程 本地部署 有 2026-04-26
Context7 831acf40 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

开发工具
字段来自项目仓库与公开索引,中文说明由本站标注
提供方drumnation上游标注的维护方 drumnation
分类开发工具本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式无需鉴权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时@smithery/cli · Node.js本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

16.4 KB
来自项目仓库与上游目录的原文,未做删改

🖼️ Unsplash智能MCP服务器

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

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

🚀 为什么选择这种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. 克隆存储库:```bash
    git clone https://github.com/drumnation/unsplash-smart-mcp-server.git
    cd unsplash-smart-mcp-server

2. 安装依赖项:```bash
npm install
  1. 配置光标MCP设置:
  • macOS:编辑 ~/.cursor/mcp.json
  • Windows:编辑 %USERPROFILE%\.cursor\mcp.json
  • Linux:编辑 ~/.cursor/mcp.json
  1. 添加以下配置:```json
    {
    "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密钥

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

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

### 游标CLI替代方案

如果您更喜欢使用Cursor的CLI:```bash
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. 克隆存储库:```bash
    git clone https://github.com/drumnation/unsplash-smart-mcp-server.git
    cd unsplash-smart-mcp-server

2. 创建一个 `docker-compose.yml` 文件:```yaml
services:
unsplash-mcp:
build: .
image: unsplash-mcp-server
restart: always
stdin_open: true
tty: true
environment:
- UNSPLASH_ACCESS_KEY=your_api_key_here
  1. 构建并启动容器:```bash
    docker-compose up -d

4. 配置光标MCP设置:

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

1. 添加以下配置:```json
{
"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中安装服务器:```bash
    npx @smithery/cli install @drumnation/unsplash-smart-mcp-server --client cursor --key your_api_key_here

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

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

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

## 🧩 与AI代理集成

### Cursor中Claude的分步指南

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

1. **发起请求**:只需向克劳德索要一张自然语言的图片
1. **AI解读**:克劳德了解您的需求,并致电 `stock_photo` 具有优化参数的工具
1. **智能图像选择**:服务器解释上下文并找到最相关的图像
1. **选项介绍**:Claude为您呈现最佳匹配和下载命令
1. **无缝下载**:执行建议的命令,将图像精确地放置在需要的位置
1. **自动归因**:所有归因数据都已存储,可以在需要时访问

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

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

### 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:直接节点执行(推荐)```json

{
"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方法```json
{
"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的要求,而无需任何额外的努力。

归因管理系统

服务器包括一个全面的归因管理系统:```javascript
// 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**:用于自定义实现的结构化数据
1. **超文本标记语言**:网站页脚或致谢部分的现成HTML页面
1. **反应**:现代web应用程序的嵌入式React组件

## 💼 开发人员工作流集成

### 真实世界用例

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

#### 前端开发

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

#### 文档

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

#### 内容创建

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

#### 应用开发

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

### 框架特定组织

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

|框架|默认图像路径|备用路径|
|-----------|-------------------|----------------|
|Next.js| `/public/images/` | `/public/assets/images/` |
|反应| `/src/assets/images/` | `/assets/images/` |
|查看| `/src/assets/images/` | `/public/images/` |
|角度| `/src/assets/images/` | `/assets/images/` |
|通用| `/assets/images/` | `~/Downloads/stock-photos/` |

## 🥇 竞争差别化

### 为什么选择我们的Unsplash集成?

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

## ⚙️ 配置

### 环境变量

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

### 刀具参数

#### 库存_照片

|参数|类型|描述|默认值|
|-----------|------|-------------|---------|
| `query` |string |要搜索什么(如果未指定,AI将选择)|-|
| `purpose` |string |图像将在何处使用(例如,英雄、背景)|-|
| `count` |number |要返回的图像数量| `1` |
| `orientation` |string |首选方向(任意、横向、纵向、方形)| `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` |

#### 获取分配

|参数|类型|描述|默认值|
|-----------|------|-------------|---------|
| `format` |string |输出格式(json、html、react)| `json` |
| `projectPath` |string |筛选特定项目路径的属性|-|
| `outputPath` |string |保存归因文件的位置|-|

## 🔧 故障排除

### 常见问题及解决方法

|问题|解决方案|
|-------|----------|
| **连接被拒绝** |确保服务器在配置的端口上运行|
| **认证错误** |验证Unsplash API密钥设置是否正确|
| **未找到图像** |尝试更广泛的搜索词或检查您的搜索查询|
| **下载权限问题** |使用 `downloadMode: 'urls_only'` 以及手动下载命令|
| **Docker容器过早退出** |确保您正在使用 `CMD ["npm", "start"]` 而不是直接用tsx运行TypeScript文件。这确保了服务器在Docker环境中保持运行。 |
| **超时错误** |默认的MCP超时为60秒,这可能不足以下载更大的图像或处理多个图像。对于图像密集型操作:1)每次请求处理较少的图像,2)使用较小的图像尺寸,3)考虑使用 `urls_only` 模式而不是自动下载,4)检查网络连接|
| **未找到归因** |验证映像是否已通过MCP服务器下载|
| **未处理的MCP错误** |如果你看到 `"McpError: MCP error -32001: Request timed out"` 错误,您的请求可能需要太长时间。将其分解为更小的操作或使用仅URL的方法|

## 🤝 贡献

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

### 开发工作流程

1. 克隆仓库
1. 安装依赖项 `npm install`
1. 创建一个 `.env` 使用Unsplash API密钥文件
1. 在开发模式下运行 `npm run dev`
1. 使用运行测试 `npm test`

## 🗺️ 路线图

以下是我们对未来版本的计划:

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

## 📄 许可证

MIT许可证

## 📚 归因要求

使用Unsplash的图像时,您必须遵守 Unsplash许可证:

- 不需要署名,但值得赞赏
- 您不能出售未经更改的照片副本
- 您无法从Unsplash编译照片以创建竞争服务

我们的服务器归因系统可以很容易地为摄影师提供适当的信用。

## 📞 联系

如有任何问题或疑问,请 打开一个问题 在GitHub上。

## 🧰 开发和测试

### 在本地运行服务器```bash
# 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

测试

该软件包包括一个全面的测试套件:```bash

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.

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Unsplash Smart MCP Server (unsplash-smart-mcp-server) 怎么安装?

在客户端按下面的安装命令接入:npx @smithery/cli install @drumnation/unsplash-smart-mcp-server --client cursor --key your_api_key_here。对应的包名是 @smithery/cli。装完在客户端配置里引用同一个包或端点。

Unsplash Smart MCP Server (unsplash-smart-mcp-server) 怎么在 Claude、Cursor 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Unsplash Smart MCP Server (unsplash-smart-mcp-server) 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Unsplash Smart MCP Server (unsplash-smart-mcp-server) 需要 API Key 吗?

资料标注为无需认证,装好就能连;如果实际调用时报鉴权错误,按官方文档补上凭据。

Unsplash Smart MCP Server (unsplash-smart-mcp-server) 支持哪些客户端?

资料标注支持 Claude、Cursor;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Unsplash Smart MCP Server (unsplash-smart-mcp-server) 能提供哪些能力?

资料显示约 2 个工具;能力标签包括 开发工具、TypeScript、Claude、上下文感知。具体工具清单以官方文档为准。

Unsplash Smart MCP Server (unsplash-smart-mcp-server) 需要什么运行环境?

运行时为 Node.js;属于本地进程,需要在本机装好运行环境。

Unsplash Smart MCP Server (unsplash-smart-mcp-server) 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。