unsplash

Unsplash MCP Server provides an integration layer to search for high-quality Unsplash images from within your MCP-enabled workflow. It exposes a search_photos capability that lets you query the Unsplash catalog with filters such as keywords, color schemes, orientation, and sorting/pagination options. To use it, configure the server in your MCP client (for example Cursor) and supply your Unsplash Access Key via the UNSPLASH_ACCESS_KEY environment variable. Once running, you can invoke the search_photos tool with fields like query, per_page, and orientation to retrieve matching image results that you can embed or reference in your application.

Prerequisites:

• Python 3.9+ installed on your system
• Access to install Python packages (pip)

Manual installation steps:

1. Clone the repository (or prepare the server directory): git clone https://github.com/hellokaton/unsplash-mcp-server.git cd unsplash-mcp-server

2. Create and activate a Python virtual environment (optional but recommended): python -m venv venv source venv/bin/activate # On Windows: .\venv\Scripts\activate

3. Install dependencies from PyPI (the project is typically configured as a package): pip install .

4. Obtain an Unsplash Access Key:

   • Create a developer account at https://unsplash.com/developers
   • Register an application and copy the Access Key
   • Set the key in your environment or in your MCP config as UNSPLASH_ACCESS_KEY

5. Run or configure the MCP server via your preferred runtime (see mcp_config):

   • If using uv: uvx run --with fastmcp fastmcp run ./server.py

6. If integrating with an editor/CLI (e.g., Cursor), add the provided mcpServers entry to your settings.json as shown in the repository docs.

Tips and common issues:

• Ensure your UNSPLASH_ACCESS_KEY is valid and has the necessary permissions for the endpoints you intend to use.
• If running in a restricted environment, set absolute paths for ./server.py and ensure uv (or Python) is accessible in the system PATH.
• When using Cursor or other editors, update the environment key placeholder with your actual Unsplash key and adjust the path to server.py if needed.
• The available tool is search_photos; you can customize the query with fields like query, per_page, and orientation (e.g., landscape or portrait).
• If you encounter rate limiting from the Unsplash API, consider implementing caching or reducing request frequency in your application logic.