unsplash -go

This MCP server exposes a set of tools to interact with Unsplash photo data via Model Context Protocol. The available tools are search_photos, get_photo, and random_photo. You can connect using standard MCP I/O to issue tool invocations in a structured format, or use Server-Sent Events (SSE) for a streaming connection to receive results as they are produced. The server relies on an Unsplash API access key provided via the UNSPLASH_ACCESS_KEY environment variable, so be sure to configure that in your environment when running through Docker or your chosen deployment method.

To use, first ensure the server is running (for example, via Docker as shown in the installation instructions). From your client, call search_photos with a query to find relevant images, including optional pagination and color/orientation filters. Use get_photo with a specific photoId to retrieve detailed metadata for a photo, including EXIF data and photographer information. Use random_photo to fetch one or more random images, with optional filters such as collections, topics, orientation, and safety filters. These tools can be chained with your LLM prompts to fetch contextually relevant images and metadata for your conversations.

Prerequisites:

• Docker installed and running (recommended for this MCP server) or Go environment if you prefer building from source
• An Unsplash API access key (UNSPLASH_ACCESS_KEY)

Option A: Run via Docker (recommended)

1. Ensure Docker is installed and running
2. Pull and run the MCP server image docker run -e UNSPLASH_ACCESS_KEY=your-access-key -it okooo5km/unsplash-mcp-server-go
3. The server will start and listen for MCP tool invocations over standard I/O within the container session

Option B: Build and run from source (Go)

1. Prerequisites: Go installed (1.18+)
2. Clone the repository git clone https://github.com/okooo5km/unsplash-mcp-server-go.git cd unsplash-mcp-server-go
3. Build the binary (if the repository provides a main package) go build -o unsplash-mcp-server
4. Run the binary with the required environment variable export UNSPLASH_ACCESS_KEY=your-access-key ./unsplash-mcp-server

Option C: Other deployment options If you publish a Docker image or a different container registry, adjust the docker run command accordingly and pass the UNSPLASH_ACCESS_KEY as an environment variable.

Note: Regardless of the method, ensure that the UNSPLASH_ACCESS_KEY is available to the server process, as it is required to access Unsplash APIs.

Environment variables and configuration:

• UNSPLASH_ACCESS_KEY: Your Unsplash API access key (required)
• If running under Docker, you can pass the key with -e UNSPLASH_ACCESS_KEY=your-key
• The MCP tool set includes search_photos (query, page, per_page, order_by, color, orientation), get_photo (photoId), and random_photo (count, collections, topics, username, query, orientation, content_filter, featured).

Common issues:

• Missing or invalid UNSPLASH_ACCESS_KEY will cause API calls to fail. Ensure the key is valid and not expired.
• Rate limits from the Unsplash API may apply; consider caching results in your client or applying pagination carefully.
• When using SSE mode, ensure your client supports streaming responses and handles partial data correctly.

Tips:

• Use search_photos with color and orientation filters to refine results for UI or prompt contexts.
• Retrieve detailed EXIF and photographer information via get_photo to enrich image captions or metadata in prompts.
• Use random_photo with appropriate filters to fetch diverse samples for prompt testing.