Unsplash MCP Server

🚀 Unsplash MCP Server

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

English | Traditional Chinese

A simple MCP server for seamless integration of .unsplash images with search functionality.

🚀 Quick Start

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

✨ Features

• Advanced Image Search: Search Unsplash's vast image library with the following filtering criteria:
  • Keyword relevance
  • Color scheme
  • Orientation options
  • Custom sorting and pagination

🔑 Obtaining an Unsplash Access Key

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

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

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 --key 7558c683-****-****

Windsurf

npx -y @smithery/cli@ latest install @hellokaton/unsplash-mcp-server --client windsurf --key 7558c683-****-****

Cline

npx -y @smithery/cli@ latest install @hellokaton/unsplash-mcp-server --client cline --key 7558c683-****-****

Manual Installation

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

# Switch 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 installation:

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

{
  "mcpServers": {
    "unsplash": {
      "command": "uv",
      "args": ["run", "--with", "fastmcp", "fastmcp", "run", "./server.py"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "${YOUR_ACCESS_KEY}"
      }
    }
  }
}

💻 Usage Examples

Basic Usage

Search Photos

{
  "tool": "search_photos",
  "query": "your_search_query",
  "page": 1,
  "per_page": 20
}

📚 Documentation

• Unsplash API documentation
• Python example code

📄 License

MIT License

Contact

• Project URL: GitHub
• Author's Email: [hello@katon.dev]