Unsplash MCP Server

Unsplash MCP 服务

一个提供 Unsplash 照片搜索和获取功能的模型上下文协议服务。此服务使大模型能够从 Unsplash 的海量照片库中搜索、获取照片和随机照片。这是一个 Go 实现，提供 search_photos、get_photo 和 random_photo 等工具。

✨ 功能

• 高级图片搜索：通过以下筛选条件搜索 Unsplash 的海量照片库：
  • 关键词相关性
  • 配色方案
  • 方向选项
  • 自定义排序和分页
• 详细照片信息：获取特定照片的全面详情，包括 EXIF 数据、位置和摄影师信息
• 随机照片选择：通过灵活的筛选选项获取随机照片
• 多种连接模式：
  • 用于直接集成大模型的标准 I/O 模式
  • 用于 Web 连接的服务器发送事件（SSE）模式

可用工具

• search_photos - 搜索 Unsplash 上的照片

  • query（字符串，必需）：搜索关键词
  • page（数字，可选）：页码（从 1 开始），默认值：1
  • per_page（数字，可选）：每页结果数（1-30），默认值：10
  • order_by（字符串，可选）：排序方式（relevant 或 latest），默认值："relevant"
  • color（字符串，可选）：颜色筛选（black_and_white、black、white、yellow、orange、red、purple、magenta、green、teal、blue）
  • orientation（字符串，可选）：方向筛选（landscape、portrait、squarish）

• get_photo - 获取特定照片的详细信息

  • photoId（字符串，必需）：要获取的照片 ID

• random_photo - 获取一张或多张随机照片

  • count（数字，可选）：要返回的照片数量（默认值：1；最多：30）
  • collections（字符串，可选）：用于筛选结果的公开合集 ID。多个 ID 以逗号分隔
  • topics（字符串，可选）：用于筛选结果的公开主题 ID。多个 ID 以逗号分隔
  • username（字符串，可选）：将结果限制为特定用户的照片
  • query（字符串，可选）：将结果限制为匹配搜索词的照片
  • orientation（字符串，可选）：按照片方向筛选。有效值：landscape、portrait、squarish
  • content_filter（字符串，可选）：按内容安全级别限制结果。有效值：low、high
  • featured（布尔值，可选）：将结果限制为精选照片

安装

选项 1：下载预构建二进制文件

从 GitHub Releases 页面下载适用于你平台的最新预构建二进制文件，并按照以下安装说明操作。

# Download the arm64 version
curl -L https://github.com/okooo5km/unsplash-mcp-server-go/releases/latest/download/unsplash-mcp-server-macos-arm64.zip -o unsplash-mcp-server.zip
unzip unsplash-mcp-server.zip
chmod +x unsplash-mcp-server

# Remove quarantine attribute to avoid security warnings
xattr -d com.apple.quarantine unsplash-mcp-server

# Install to your local bin directory
mkdir -p ~/.local/bin
mv unsplash-mcp-server ~/.local/bin/
rm unsplash-mcp-server.zip

# Download the x86_64 version
curl -L https://github.com/okooo5km/unsplash-mcp-server-go/releases/latest/download/unsplash-mcp-server-macos-x86_64.zip -o unsplash-mcp-server.zip
unzip unsplash-mcp-server.zip
chmod +x unsplash-mcp-server

# Remove quarantine attribute to avoid security warnings
xattr -d com.apple.quarantine unsplash-mcp-server

# Install to your local bin directory
mkdir -p ~/.local/bin
mv unsplash-mcp-server ~/.local/bin/
rm unsplash-mcp-server.zip

# Download the universal version
curl -L https://github.com/okooo5km/unsplash-mcp-server-go/releases/latest/download/unsplash-mcp-server-macos-universal.zip -o unsplash-mcp-server.zip
unzip unsplash-mcp-server.zip
chmod +x unsplash-mcp-server

# Remove quarantine attribute to avoid security warnings
xattr -d com.apple.quarantine unsplash-mcp-server

# Install to your local bin directory
mkdir -p ~/.local/bin
mv unsplash-mcp-server ~/.local/bin/
rm unsplash-mcp-server.zip

# Download the amd64 version
curl -L https://github.com/okooo5km/unsplash-mcp-server-go/releases/latest/download/unsplash-mcp-server-linux-amd64.tar.gz -o unsplash-mcp-server.tar.gz
tar -xzf unsplash-mcp-server.tar.gz
chmod +x unsplash-mcp-server

# Install to your local bin directory
mkdir -p ~/.local/bin
mv unsplash-mcp-server ~/.local/bin/
rm unsplash-mcp-server.tar.gz

# Download the arm64 version
curl -L https://github.com/okooo5km/unsplash-mcp-server-go/releases/latest/download/unsplash-mcp-server-linux-arm64.tar.gz -o unsplash-mcp-server.tar.gz
tar -xzf unsplash-mcp-server.tar.gz
chmod +x unsplash-mcp-server

# Install to your local bin directory
mkdir -p ~/.local/bin
mv unsplash-mcp-server ~/.local/bin/
rm unsplash-mcp-server.tar.gz

确保安装目录位于 PATH 中：

• macOS/Linux：将 export PATH="$HOME/.local/bin:$PATH" 添加到 shell 配置文件（.bashrc、.zshrc 等）
• Windows：通过“系统属性”>“环境变量”对话框，将目录添加到系统 PATH

选项 2：从源代码构建

1. 克隆仓库：

   git clone https://github.com/okooo5km/unsplash-mcp-server-go.git
   cd unsplash-mcp-server-go
   

2. 构建项目：

   使用 Make（推荐）：

   # Build for your current platform
   make
   
   # Or build for a specific platform
   make build-darwin-universal    # macOS Universal Binary
   make build-darwin-arm64        # macOS Apple Silicon
   make build-darwin-amd64        # macOS Intel
   make build-linux-amd64         # Linux x86_64
   make build-linux-arm64         # Linux ARM64
   make build-windows-amd64       # Windows x86_64
   
   # Or build for all platforms at once
   make build-all
   
   # Create distribution packages for all platforms
   make dist
   

   二进制文件将放置在 .build 目录中。

   直接使用 Go：

   go build -o unsplash-mcp-server
   

3. 安装二进制文件：

   # Install to user directory (recommended, no sudo required)
   mkdir -p ~/.local/bin
   cp unsplash-mcp-server ~/.local/bin/
   

   请将以下内容添加到 shell 配置文件中，确保 ~/.local/bin 位于 PATH 中：

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc  # or ~/.bashrc
   source ~/.zshrc  # or source ~/.bashrc
   

配置

环境变量

服务器需要 Unsplash API 访问密钥才能运行。请在环境中设置该密钥：

export UNSPLASH_ACCESS_KEY="your-access-key-here"

• Unsplash API 访问密钥（在 Unsplash Developers Portal 注册）

获取 Unsplash API 访问密钥

1. 前往 Unsplash Developers Portal
2. 注册或登录 Unsplash 账号
3. 注册新应用
4. 接受 API 使用条款和指南
5. 填写应用详情（名称、描述等）
6. 注册完成后，你将收到访问密钥（也称为 Client ID）

为 Claude.app 配置

添加到你的 Claude 设置中：

"mcpServers": {
  "unsplash": {
    "command": "unsplash-mcp-server",
    "env": {
      "UNSPLASH_ACCESS_KEY": "your-access-key-here"
    }
  }
}

为 Cursor 配置

将以下配置添加到 Cursor 编辑器的 settings.json 中：

{
  "mcpServers": {
    "unsplash": {
      "command": "unsplash-mcp-server",
      "env": {
        "UNSPLASH_ACCESS_KEY": "your-access-key-here"
      }
    }
  }
}

为 Chatwise 配置

注意：在 Chatwise 中添加环境变量时，请勿用引号括住值（修复 #1）

命令行参数

服务器支持以下命令行参数：

• -h, --help：显示有关服务器、其用法和可用选项的帮助信息
• -v, --version：显示 unsplash-mcp-server 的版本号
• -t, --transport <string>：要使用的传输类型（默认值：“stdio”）
  • stdio：用于与大模型直接集成的标准输入/输出模式
  • sse：用于 Web 连接的 Server-Sent Events 模式
• -p, --port <int>：以 SSE 模式运行时使用的端口（默认值：8080）

使用示例：

# Display help information
unsplash-mcp-server --help

# Display version information
unsplash-mcp-server --version

# Start server with default settings (stdio mode)
unsplash-mcp-server

# Start server in SSE mode on the default port (8080)
unsplash-mcp-server --transport sse

# Start server in SSE mode on a custom port
unsplash-mcp-server --transport sse --port 9090

以 SSE 模式运行时，可通过指定端口上的 HTTP 访问服务器，从而允许基于 Web 的客户端连接。在 stdio 模式（默认模式）下，服务器通过标准输入/输出进行通信，非常适合与大模型应用直接集成。

系统提示词示例

你可以使用以下系统提示词，帮助 Claude 有效使用 unsplash-mcp-server：

You have access to Unsplash photo search tools through MCP. You can:

1. Search for photos using specific keywords, colors, or orientations:
   - Use the search_photos tool to find images on any topic
   - Filter by color or orientation as needed
   - You can page through results and control how many appear per page

2. Get detailed information about specific photos:
   - Use get_photo with a photo ID to retrieve comprehensive details
   - This includes EXIF data, location info, and photographer details

3. Fetch random photos with customizable filters:
   - Use random_photo tool to get surprise images based on criteria
   - Filter random selections by topic, collection, username, etc.

When the user asks for images, use these tools to find relevant Unsplash photos.
Include photo URLs in your responses so users can view the images.

开发要求

• Go 1.20 或更高版本
• Unsplash API 访问密钥
• MCP Go SDK 0.19.0 或更高版本

使用示例

搜索照片

{
  "query": "mountain landscape",
  "per_page": 5,
  "color": "blue",
  "orientation": "landscape"
}

获取照片详情

{
  "photoId": "Dwu85P9SOIk"
}

获取随机照片

{
  "count": 3,
  "query": "coffee",
  "orientation": "portrait"
}

版本历史

请查看 GitHub Releases，了解版本历史和更新日志。

☕️ 支持项目

如果你觉得 unsplash-mcp-server 很有用，请考虑支持其开发：

• ⭐️ 在 GitHub 上为项目点星
• 🐛 在问题跟踪器中报告 Bug 或提出功能建议
• 🔄 提交拉取请求，帮助改进代码
• 💝 通过以下方式支持：

unsplash-mcp-server-go 基于 MIT 许可证授权。这意味着您可以自由使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。详情请参阅项目仓库中的 LICENSE 文件。