Unsplash MCP Server Go

🚀 Unsplash MCP Server

A lightweight, open-source relay server designed to interact with the Unsplash API, tailored for editors and other language models.

🚀 Quick Start

The Unsplash MCP Server is a versatile tool that enables seamless interaction with the Unsplash API. It offers a range of features and can be easily integrated into various applications.

✨ Features

• Supports integration with language models via the MCP protocol.
• Provides multiple functions, including photo search, detailed photo information retrieval, and random photo access.
• Highly flexible, supporting custom filtering conditions and paginated browsing.
• Offers detailed documentation and technical support.

📦 Installation

Using Pre-built Binaries

Choose the appropriate version based on your operating system:

Building from Source Code

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

📚 Documentation

Required Environment Variables

• UNSPLASH_ACCESS_KEY: The Unsplash API access key for authentication. Refer to the Unsplash Developer Documentation to obtain it.

Service Configuration

Create a file named config.json with the following content:

{
  "transport": "stdio",
  "port": 8080,
  "api_key": "your_unsplash_api_key_here"
}

💻 Usage Examples

Searching for Photos

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

Getting Photo Details

{
  "photoId": "Dwu85P9SOIk"
}

Randomly Getting Photos

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

Usage Scenarios

• Integration into Editors: Provide photo search functionality for editors such as Cursor and VS Code.
• AI Chatbots: Enhance the chat experience by supporting the insertion of image links.
• Personal Projects: Quickly add Unsplash photo search functionality.

Command-line Arguments

The following command-line options are supported:

• -h, --help: Display the server's help information.
• -v, --version: Display the server version number.
• -t, --transport <string>: Set the transport type (default: "stdio").
  • stdio: Standard input/output mode for direct integration with language models.
  • sse: HTTP-based Server-Sent Events mode.
• -p, --port <int>: Specify the listening port for SSE mode (default: 8080).

Example Configurations

Configuration in Cursor

Add the following to the settings.json in the Cursor editor:

{
  "mcpServers": {
    "unsplash": {
      "command": "unsplash-mcp-server",
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_access_key_here"
      }
    }
  }
}

Configuration in Chatwise

⚠️ Important Note

When adding environment variables in Chatwise, do not enclose the values in quotes (fixes issue #1).

Development Requirements

• Go 1.20 or higher.
• Unsplash API access key.
• MCP Go SDK 0.19.0 or higher.

Support the Project

If you find this project helpful, consider supporting its development:

• Star the project on GitHub.
• Report bugs or suggest features in the issue tracker.
• Submit pull requests to help improve the code.
• Contribute to the project's growth.

Special Thanks

📄 License

The unsplash-mcp-server-go is released under the MIT License. This means you are free to use, modify, and distribute the software while retaining the copyright and license notices.