Hellokaton Unsplash MCP Server

🚀 Unsplash MCP Server

A simple MCP server for seamless integration of Unsplash images and search functionality.

English | Simplified Chinese

A simple MCP server for seamlessly integrating Unsplash images and search functionality.

🚀 Quick Start

The Unsplash MCP Server is designed for searching high - quality images. It's suitable for developers who want to integrate Unsplash functionality into their own applications.

✨ Features

• Advanced Image Search: Search the vast Unsplash image library with the following filters supported:
  • Keyword relevance
  • Color scheme
  • Landscape or portrait orientation
  • Custom sorting and pagination

🔑 Obtaining an Unsplash Access Key

Before installing this server, you need to obtain an Unsplash API access key:

1. Register a developer account on Unsplash.
2. Create a new application.
3. Retrieve your access key from the application details page.
4. Use this key in the following configuration steps.

For more details, refer to the official Unsplash API documentation.

📦 Installation

Automatically install the Unsplash image integration server via Smithery:

IDE Setup

Cursor IDE

npx -y @smithery/cli@latest install @hellokaton/unsplash-mcp-server --client cursor --config "{\"unsplashAccessKey\":\"YOUR_ACCESS_KEY\"}"

Windsurf

npx -y @smithery/cli@latest install @hellokaton/unsplash-mcp-server --client windsurf --config "{\"unsplashAccessKey\":\"YOUR_ACCESS_KEY\"}"

Cline

npx -y @smithery/cli@latest install @hellokaton/unsplash-mcp-server --client cline --config "{\"unsplashAccessKey\":\"YOUR_ACCESS_KEY\"}"

Manual Installation

# Clone the repository
git clone https://github.com/hellokaton/unsplash-mcp-server.git

# Navigate to the project directory
cd unsplash-mcp-server

# Create a virtual environment
uv venv

# Install dependencies
uv pip install .

Cursor Editor Integration Add the following configuration to your Cursor editor's settings.json:

⚠️ Important Note

Please adjust the following configuration according to the actual situation:

• If uv is not in the system PATH, use an absolute path (e.g., /path/to/uv).
• ./server.py should be modified to the actual location of your server script (you can use an absolute path or a path relative to the workspace).

// Configuration example:
{
  "customCss": "",
  "customHtml": "",
  "language": "zh-CN",
  "theme": "vs-dark"
}

🛠️ Tools

Installing Dependencies

Ensure the following tools are installed:

• Python 3.9+
• Node.js (if you need to build the project)

Running the Server

The command to run the server is as follows:

uv run server.py

Visit http://localhost:5000 to view the results.

📚 Documentation

For more detailed information, refer to the official documentation.

🔗 Other Implementations

• Unsplash Official Website
• GitHub Repository

Thank you for using! If you have any questions, please feel free to contact the maintainers.