unsplash_search
Search for high-quality photos on Unsplash to find relevant images for country profiles. Filter results by orientation and specify the number of photos needed for your project.
Instructions
Search for photos on Unsplash using the given query.
Args: query: Search term for photos num_results: Number of photos to return (1-30, default: 10) orientation: Filter by orientation - 'landscape', 'portrait', or 'squarish' (optional)
Returns: JSON string containing search results with photo URLs and metadata
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| num_results | No | ||
| orientation | No | ||
| query | Yes |
Implementation Reference
- server.py:26-30 (handler)MCP tool handler for 'unsplash_search'. This decorated function (@mcp.tool()) registers and implements the tool logic by instantiating UnsplashSearcher and calling its search_photos method.@mcp.tool() def unsplash_search(query: str, num_results: int = 10, orientation: Optional[str] = None) -> str: """Search for photos on Unsplash using the given query.""" searcher = UnsplashSearcher() return searcher.search_photos(query, num_results, orientation)
- unsplash_searcher.py:15-97 (helper)Core helper method implementing the Unsplash API search logic, including request construction, response processing, error handling, and formatted JSON output.def search_photos(self, query: str, num_results: int = 10, orientation: Optional[str] = None) -> str: """ Search for photos on Unsplash using the given query. Args: query: Search term for photos num_results: Number of photos to return (1-30, default: 10) orientation: Filter by orientation - 'landscape', 'portrait', or 'squarish' (optional) Returns: JSON string containing search results with photo URLs and metadata """ if not self.api_key: return "Error: UNSPLASH_API_KEY environment variable not set. Please add your Unsplash API key to your .env file." # Validate num_results parameter num_results = max(1, min(30, num_results)) # Build the API URL url = f"{self.base_url}/search/photos" headers = { "Authorization": f"Client-ID {self.api_key}", "Accept-Version": "v1" } params = { "query": query, "per_page": num_results } # Add orientation filter if specified if orientation and orientation.strip() and orientation.lower() in ['landscape', 'portrait', 'squarish']: params["orientation"] = orientation.lower() try: response = requests.get(url, headers=headers, params=params) response.raise_for_status() data = response.json() # Format the results for better readability results = { "total": data.get("total", 0), "total_pages": data.get("total_pages", 0), "photos": [] } for photo in data.get("results", []): photo_info = { "id": photo.get("id"), "description": photo.get("description", "No description"), "alt_description": photo.get("alt_description", "No alt description"), "width": photo.get("width"), "height": photo.get("height"), "color": photo.get("color"), "likes": photo.get("likes"), "urls": { "raw": photo.get("urls", {}).get("raw"), "full": photo.get("urls", {}).get("full"), "regular": photo.get("urls", {}).get("regular"), "small": photo.get("urls", {}).get("small"), "thumb": photo.get("urls", {}).get("thumb") }, "user": { "name": photo.get("user", {}).get("name"), "username": photo.get("user", {}).get("username"), "portfolio_url": photo.get("user", {}).get("portfolio_url") }, "links": { "html": photo.get("links", {}).get("html"), "download": photo.get("links", {}).get("download") } } results["photos"].append(photo_info) return json.dumps(results, indent=2) except requests.exceptions.RequestException as e: return f"Error making request to Unsplash API: {str(e)}" except json.JSONDecodeError as e: return f"Error parsing response from Unsplash API: {str(e)}" except Exception as e: return f"Unexpected error: {str(e)}"