home / mcp / unsplash mcp server

Unsplash MCP Server

🔎 A MCP server for Unsplash image search.

Installation

Add the following to your MCP client configuration file.

Configuration

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

You can run the Unsplash MCP Server to add powerful image search capabilities to your applications. It exposes a simple MCP interface that lets you search for high-quality Unsplash photos and integrate results into your workflows or dev tools with ease.

How to use

You interact with the Unsplash MCP Server through an MCP client. Once the server is running, you can perform image searches by invoking the built‑in search tool and specifying your query, preferred results per page, and optional orientation. Use the client to request photos matching your keywords and apply filters such as color, orientation, and sort order to tailor results to your UI or workflow.

How to install

Prerequisites: Python is installed on your system, and you have a modern shell available. You will also need an Unsplash API Access Key to enable image search.

Manual setup steps you can follow to run the server locally could include creating a Python virtual environment, installing dependencies, and starting the server. The following steps reflect a typical flow for Python MCP servers that ship with a uvx-based runtime.

Configuration and running the server

Configure the MCP client to connect to the Unsplash MCP Server. You will provide your Unsplash Access Key to authorize requests.

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

Using in Cursor Editor Integration

If you use the Cursor editor, add the Unsplash MCP server configuration to the editor’s settings so you can launch and test image searches directly from your development workspace.

Tools and capabilities

The server provides a search tool to query Unsplash’s photo library. You can specify a keyword, result count per page, and orientation to retrieve curated image results suitable for your application’s UI.

Available tools

search_photos

Query Unsplash for photos using your search terms, with configurable per_page and orientation to control result count and layout.