🖼️ 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访问密钥(在这里买一个)
本地安装(推荐)
- 克隆存储库:```bash
git clone https://github.com/drumnation/unsplash-smart-mcp-server.git
cd unsplash-smart-mcp-server
2. 安装依赖项:```bash
npm install
- 配置光标MCP设置:
- macOS:编辑
~/.cursor/mcp.json - Windows:编辑
%USERPROFILE%\.cursor\mcp.json - Linux:编辑
~/.cursor/mcp.json
- 添加以下配置:```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(最可靠的方法)
- 克隆存储库:```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
- 构建并启动容器:```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": {}
}
}
}
- 保存文件并重新启动Cursor。
此设置将:
- Docker启动时自动启动服务器
- 如果服务器崩溃,请重新启动服务器
- 在后台运行,无需终端窗口
- 提供与Cursor的可靠连接
Via Smithery(云部署)
如果你更喜欢云部署,你可以使用Smithery:
- 通过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优先的方法,而不是直接嵌入图像,原因有几个:
- 存储效率:防止AI代理在其上下文中不必要地存储大型二进制数据
- 带宽节约:减少服务之间的数据传输,缩短响应时间
- 安置灵活性:允许开发人员在需要的地方下载图像
- 权限管理:避免受限环境中的文件系统权限问题
- 工作流集成:与现有开发管道无缝集成
该策略使AI代理能够根据项目上下文智能地建议最佳下载位置,而不受自身环境限制的约束。
最小化工具垃圾邮件和API调用
与其他需要多个工具调用来搜索、过滤、下载和归因图像的解决方案不同,我们的服务器:
- 统一整个图像工作流程 变成一个单一
stock_photo工具 - 优化结果检索 通过预先请求更多图像来实现更好的过滤
- 消除乒乓球互动 在代理和服务之间
- 减少代理令牌的使用 通过简化请求和响应格式
这种设计显著减少了API调用和工具调用的数量,从而实现更快的结果和更低的运营成本。
🔄 自动归因和合规
Unsplash服务条款:轻松合规
使用Unsplash的图像需要遵守其 服务条款。我们的服务器会自动处理此问题:
- 归因数据采集:每次图像下载都会自动存储摄影师信息
- 元数据嵌入:摄影师的详细信息直接嵌入到图像文件中
- 归因数据库:本地数据库保存所有图像使用情况的记录
- 归因生成器:内置工具创建HTML和React归因组件
- 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.
