Upsplash MCP Server

🚀 Unsplash 項目文檔

本項目是一個實現與 Unsplash API 交互的 MCP（管理控制平面）服務器。藉助該服務器，用戶能夠通過命令行工具便捷地搜索和下載圖片。

⚠️ 重要提示

徽章鏈接中的用戶名 "benjaming" 需要替換為實際的中文項目負責人或團隊名稱。同時，請將代碼倉庫鏈接中的 yourusername 替換為實際的 GitHub 賬號。

🚀 快速開始

下載與安裝

方法一：使用 Git 克隆倉庫

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

方法二：使用 npm 安裝（假設已發佈到 npm）

npm install -g unsplash-mcp-server

啟動服務

• 開發模式

  npm run dev
  

• 生產環境

  npm start
  

✨ 主要特性

1. 搜索圖片：支持通過關鍵詞、作者和其他篩選條件搜索 Unsplash 上的圖片。
2. 分頁瀏覽：可以按指定數量獲取每一頁的結果，方便處理大量數據。
3. 按方向篩選：用戶可以選擇垂直或水平方向的圖片進行搜索。
4. 下載功能：支持下載不同分辨率（如小、中、大）的圖片。
5. 環境配置：通過環境變量 UNSPLASH_ACCESS_KEY 配置訪問密鑰，便於身份驗證。

📦 安裝指南

下載與安裝

方法一：使用 Git 克隆倉庫

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

方法二：使用 npm 安裝（假設已發佈到 npm）

npm install -g unsplash-mcp-server

啟動服務

• 開發模式

  npm run dev
  

• 生產環境

  npm start
  

💻 使用示例

基礎用法

搜索圖片 (search_photos)

cline search_photos --query "nature" --per_page 10 --orientation landscape

輸入參數：

• --query：必填，搜索關鍵詞。
• --page：可選，默認為第一頁。
• --per_page：每頁結果數量，默認為 20。
• --orientation：可選，篩選圖片方向（portrait 或 landscape）。

輸出結果：返回 JSON 格式的搜索結果列表，包含圖片 ID、URL 等信息。

下載圖片 (download_photo)

cline download_photo --photo_id abc123 --size large

輸入參數：

• --photo_id：必填，目標圖片的唯一標識符。
• --size：可選，默認為中等分辨率。

📚 詳細文檔

代碼倉庫

• GitHub 倉庫：Unsplash API MCP 服務（請將 yourusername 替換為實際的 GitHub 賬號）

工具使用說明

搜索圖片 (search_photos)

示例命令：

cline search_photos --query "nature" --per_page 10 --orientation landscape

輸入參數：

• --query：必填，搜索關鍵詞。
• --page：可選，默認為第一頁。
• --per_page：每頁結果數量，默認為 20。
• --orientation：可選，篩選圖片方向（portrait 或 landscape）。

輸出結果：返回 JSON 格式的搜索結果列表，包含圖片 ID、URL 等信息。

下載圖片 (download_photo)

示例命令：

cline download_photo --photo_id abc123 --size large

輸入參數：

• --photo_id：必填，目標圖片的唯一標識符。
• --size：可選，默認為中等分辨率。

環境配置

創建或修改 .env 文件，添加以下內容：

UNSPLASH_ACCESS_KEY=your_actual_key_here

使用 Cline 配置 MCP 服務

在項目的 .roo/mcp.json 文件中添加以下配置：

{
  "mcpServers": {
    "unsplash-mcp-server": {
      "command": "bun",
      "args": [
        "/path/to/your/unsplash-mcp-server/build/index.js"
      ],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_actual_key_here"
      }
    }
  }
}

開發指南

運行腳本

• 開發模式

  npm run dev
  

• 生產構建

  npm run build
  

監控與調試

使用 npm run watch 命令即時監控代碼變化，並通過 npm run lint 進行代碼檢查。

📄 許可證

本項目遵循 MIT 許可證，具體內容請參考 LICENSE 文件。