AI导哈

Unsplash图片搜索服务

一个提供访问Unsplash API的模型上下文协议服务器，使AI助手能够搜索和获取高质量、免费使用的照片。

  • by mjordi
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 mjordi/unsplash-mcp-server

使用说明

Unsplash MCP服务器

一个模型上下文协议（MCP）服务器，提供对Unsplash API的访问，使人工智能助手能够搜索和检索高质量、免费使用的照片。

特性

  • 🔍 搜索照片：使用高级过滤器按关键字搜索数百万张高质量照片
  • 📸 照片详情：获取特定照片的详细信息，包括EXIF数据
  • 🎲 随机照片：获取随机照片，可选择按查询或方向过滤
  • 📚 集合：搜索和浏览精选照片集
  • 👤 用户档案：搜索摄影师并查看他们的作品集
  • 📊 统计：获取照片的查看、下载和类似统计信息
  • 🎨 高级过滤器：按方向、颜色、内容安全级别过滤
  • 📝 多种格式：JSON或Markdown格式的响应

安装

先决条件

  • Node.js 18或更高版本
  • Unsplash API访问密钥

获取Unsplash API密钥

  1. 访问 Unsplash开发者
  2. 创建帐户或登录
  3. 点击“新建应用程序”
  4. 填写所需的详细信息并接受条款
  5. 复制您的 访问密钥

备注：模拟账户每小时仅限50个请求。申请更高限额的生产访问权限。

设置

# Clone or download this repository
cd unsplash-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Set your API key
export UNSPLASH_ACCESS_KEY=your_access_key_here

用法

使用stdio运行（适用于Claude Desktop等）

npm start
# or
node dist/index.js

使用HTTP传输运行

TRANSPORT=http PORT=3000 npm start

Claude桌面配置

添加到您的Claude Desktop配置文件中：

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "unsplash": {
      "command": "node",
      "args": ["/path/to/unsplash-mcp-server/dist/index.js"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_access_key_here"
      }
    }
  }
}

可用工具

照片搜索与检索

unsplash_search_photos

使用高级过滤功能按关键字搜索照片。

参数:

  • query （字符串，必填）：搜索关键字
  • page （number）：页码（默认值：1）
  • per_page （数字）：每页结果，1-30（默认值：10）
  • orientation （string）：按“横向”、“纵向”或“方形”过滤
  • content_filter （string）：“低”（默认）或“高”安全过滤器
  • color （string）：按颜色名称过滤（例如，“黑色”、“白色”、“红色”）
  • order_by （string）：按“相关”（默认）或“最新”排序
  • response_format （string）：“markdown”（默认）或“json”

示例:

Search for: "mountain sunset"
Filter by: orientation="landscape", color="orange"

unsplash_get_photo

获取特定照片的详细信息。

参数:

  • id （字符串，必填）：Unsplash照片ID
  • response_format （string）：“markdown”或“json”

unsplash_get_random

获取一张或多张随机照片。

参数:

  • query （string）：可选搜索筛选器
  • orientation （string）：按方向过滤
  • content_filter （string）：安全过滤器级别
  • count （number）：照片数量，1-30（默认值：1）
  • response_format （string）：输出格式

unsplash_list_photos

列出Unsplash编辑提要中的照片。

参数:

  • page （编号）：页码
  • per_page （数量）：每页结果
  • order_by （string）：“最新”、“最古老”或“流行”
  • response_format （string）：输出格式

unsplash_get_statistics

获取照片的查看、下载和点赞统计信息。

参数:

  • id （字符串，必填）：照片ID
  • response_format （string）：输出格式

unsplash_track_download

跟踪照片下载（Unsplash API指南要求）。

参数:

  • id （字符串，必填）：正在下载照片ID

重要：在以编程方式下载/使用照片之前，始终调用此函数。

集合

unsplash_search_collections

搜索精选照片集。

参数:

  • query （字符串，必填）：搜索关键字
  • page （编号）：页码
  • per_page （数量）：每页结果
  • response_format （string）：输出格式

unsplash_get_collection_photos

从特定收藏中获取照片。

参数:

  • id （字符串，必填）：集合ID
  • page （编号）：页码
  • per_page （数量）：每页结果
  • orientation （string）：按方向过滤
  • response_format （string）：输出格式

用户

unsplash_search_users

搜索摄影师和用户。

参数:

  • query （字符串，必填）：搜索关键字
  • page （编号）：页码
  • per_page （数量）：每页结果
  • response_format （string）：输出格式

unsplash_get_user_photos

获取特定用户的照片。

参数:

  • username （string，必填）：Unsplash用户名
  • page （编号）：页码
  • per_page （数量）：每页结果
  • order_by （string）：“最新”、“最古老”或“流行”
  • orientation （string）：按方向过滤
  • response_format （string）：输出格式

API指南与归因

取消屏蔽API用法

使用Unsplash的照片时：

  1. 跟踪下载：总是打电话 unsplash_track_download 以编程方式下载照片时
  2. 归因：虽然不是必需的，但感谢摄影师
  3. 直接链接：直接使用Unsplash CDN URL（不要重新托管映像）
  4. 速率限制：模拟账户每小时有50个请求；生产账户有更高的限额

归因示例

Photo by [Photographer Name] on Unsplash

发展

项目结构

unsplash-mcp-server/
├── src/
│   ├── index.ts              # Main entry point
│   ├── types.ts              # TypeScript type definitions
│   ├── constants.ts          # Configuration constants
│   ├── services/
│   │   ├── unsplash-client.ts   # API client
│   │   └── formatters.ts        # Response formatting
│   ├── schemas/
│   │   └── index.ts             # Zod validation schemas
│   └── tools/
│       ├── photos.ts            # Photo-related tools
│       └── collections-users.ts # Collection/user tools
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

建筑

npm run build

使用Watch模式进行开发

npm run dev

错误处理

服务器为常见问题提供明确的错误消息：

  • 401未经授权：API密钥无效或丢失
  • 403禁止：超出速率限制或权限不足
  • 404未找到：照片、收藏或用户不存在
  • 网络错误：Unsplash API的连接问题

许可证

MIT许可证-有关详细信息，请参阅许可证文件

学分

支持

对于以下问题：

  • 此MCP服务器：在此存储库中打开一个问题
  • 取消屏蔽API：联系方式api@unsplash.com或访问 Unsplash帮助
  • MCP协议：参见 MCP文件

相关 MCP