Upsplash MCP Server

🚀 Unsplash Project Documentation

This is an MCP (Management Control Plane) server that interacts with the Unsplash API. It allows users to search for and download images via a command-line tool.

⚠️ Important Note

The username "benjaming" in the badge link needs to be replaced with the actual Chinese project leader or team name.

📦 Installation

Method 1: Clone the repository using Git

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

Method 2: Install using npm (assuming it's published on npm)

npm install -g unsplash-mcp-server

✨ Features

1. Search for images
   • Supports searching for images on Unsplash by keywords, authors, and other filtering criteria.
2. Pagination
   • Allows you to retrieve a specified number of results per page, facilitating the handling of large amounts of data.
3. Filter by orientation
   • Users can choose to search for images in either vertical or horizontal orientation.
4. Download functionality
   • Supports downloading images in different resolutions (e.g., small, medium, large).
5. Environment configuration
   • Configures the access key via the environment variable UNSPLASH_ACCESS_KEY for authentication.

💻 Usage Examples

Start the service

• Development mode

  npm run dev
  

• Production environment

  npm start
  

Search for images (search_photos)

Example command:

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

Input parameters:

• --query: Required, the search keyword.
• --page: Optional, defaults to the first page.
• --per_page: The number of results per page, defaults to 20.
• --orientation: Optional, filters images by orientation (portrait or landscape).

Output results: Returns a list of search results in JSON format, including image IDs, URLs, and other information.

Download an image (download_photo)

Example command:

cline download_photo --photo_id abc123 --size large

Input parameters:

• --photo_id: Required, the unique identifier of the target image.
• --size: Optional, defaults to medium resolution.

📚 Documentation

Environment configuration

Create or modify the .env file and add the following content:

UNSPLASH_ACCESS_KEY=your_actual_key_here

Configure the MCP service using Cline

Add the following configuration to the .roo/mcp.json file in the project:

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

Development guide

Run scripts

• Development mode

  npm run dev
  

• Production build

  npm run build
  

Monitoring and debugging

Use the npm run watch command to monitor code changes in real-time, and perform code checks using npm run lint.

📄 License

This project is licensed under the MIT License. Please refer to the LICENSE file for details.

🔗 Code Repository

• GitHub Repository: Unsplash API MCP Service (Please replace yourusername with your actual GitHub account)