{"id":49620803,"url":"https://github.com/cevatkerim/unsplash-mcp","last_synced_at":"2026-05-21T15:01:16.971Z","repository":{"id":342798275,"uuid":"1131838954","full_name":"cevatkerim/unsplash-mcp","owner":"cevatkerim","description":"An MCP server for Unsplash photo search with proper attribution built-in.  Key differentiator: Returns ready-to-use attribution_text and attribution_html for each photo, making it trivial for LLMs to build content pages with properly credited images (as required by Unsplash API guidelines).","archived":false,"fork":false,"pushed_at":"2026-01-10T19:49:20.000Z","size":7,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-29T01:56:18.578Z","etag":null,"topics":["mcp","unsplash","unsplash-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cevatkerim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-10T19:46:57.000Z","updated_at":"2026-03-27T17:35:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cevatkerim/unsplash-mcp","commit_stats":null,"previous_names":["cevatkerim/unsplash-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cevatkerim/unsplash-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cevatkerim%2Funsplash-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cevatkerim%2Funsplash-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cevatkerim%2Funsplash-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cevatkerim%2Funsplash-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cevatkerim","download_url":"https://codeload.github.com/cevatkerim/unsplash-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cevatkerim%2Funsplash-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33305277,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-21T12:23:38.849Z","status":"ssl_error","status_checked_at":"2026-05-21T12:22:11.673Z","response_time":62,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","unsplash","unsplash-api"],"created_at":"2026-05-05T02:00:24.247Z","updated_at":"2026-05-21T15:01:16.959Z","avatar_url":"https://github.com/cevatkerim.png","language":"Python","funding_links":["https://www.buymeacoffee.com/cevatkerim"],"categories":["カテゴリ"],"sub_categories":["📝 \u003ca name=\"content--media\"\u003e\u003c/a\u003eコンテンツ・メディア"],"readme":"# Unsplash MCP Server\n\nAn MCP (Model Context Protocol) server for fetching photos from [Unsplash](https://unsplash.com) with **proper attribution**. Designed for LLMs building content pages that need properly credited images.\n\n## Features\n\n- **Search Photos** - Find photos by keyword with filters (color, orientation)\n- **Random Photos** - Get random photos for variety in content\n- **Download Tracking** - Compliant with Unsplash API guidelines\n- **Full Attribution** - Every photo includes ready-to-use attribution text and HTML\n- **LLM-Optimized** - Pre-formatted attribution strings for easy embedding\n\n## Why This Server?\n\nUnsplash requires proper attribution when using their photos. This server makes it easy by including:\n\n- `attribution_text`: Plain text like \"Photo by John Doe on Unsplash\"\n- `attribution_html`: Full HTML with proper links for web pages\n\n```html\nPhoto by \u003ca href=\"https://unsplash.com/@johndoe\"\u003eJohn Doe\u003c/a\u003e on \u003ca href=\"https://unsplash.com\"\u003eUnsplash\u003c/a\u003e\n```\n\n## Installation\n\n### Prerequisites\n\n- Python 3.11+\n- An Unsplash API access key ([Get one here](https://unsplash.com/developers))\n\n### Quick Start\n\n```bash\n# Clone the repository\ngit clone https://github.com/cevatkerim/unsplash-mcp.git\ncd unsplash-mcp\n\n# Create virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install dependencies\npip install fastmcp httpx python-dotenv\n\n# Set your API key\necho \"UNSPLASH_ACCESS_KEY=your_key_here\" \u003e .env\n\n# Run the server\nfastmcp run server.py\n```\n\n## Configuration\n\n### Claude Code\n\nAdd to your `~/.claude.json` (user-level) or project `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"unsplash\": {\n      \"type\": \"stdio\",\n      \"command\": \"/path/to/unsplash-mcp/.venv/bin/fastmcp\",\n      \"args\": [\"run\", \"/path/to/unsplash-mcp/server.py\"],\n      \"env\": {\n        \"UNSPLASH_ACCESS_KEY\": \"your_access_key_here\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to your Cursor MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"unsplash\": {\n      \"command\": \"/path/to/unsplash-mcp/.venv/bin/fastmcp\",\n      \"args\": [\"run\", \"/path/to/unsplash-mcp/server.py\"],\n      \"env\": {\n        \"UNSPLASH_ACCESS_KEY\": \"your_access_key_here\"\n      }\n    }\n  }\n}\n```\n\n### Windsurf / Cline\n\nAdd to your MCP configuration:\n\n```json\n{\n  \"unsplash\": {\n    \"command\": \"/path/to/unsplash-mcp/.venv/bin/fastmcp\",\n    \"args\": [\"run\", \"/path/to/unsplash-mcp/server.py\"],\n    \"env\": {\n      \"UNSPLASH_ACCESS_KEY\": \"your_access_key_here\"\n    }\n  }\n}\n```\n\n## Tools\n\n### `search_photos`\n\nSearch for photos by keyword with optional filters.\n\n**Parameters:**\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `query` | string | required | Search keyword(s) |\n| `page` | int | 1 | Page number |\n| `per_page` | int | 10 | Results per page (1-30) |\n| `order_by` | string | \"relevant\" | Sort: \"relevant\" or \"latest\" |\n| `color` | string | null | Color filter (see below) |\n| `orientation` | string | null | \"landscape\", \"portrait\", \"squarish\" |\n| `content_filter` | string | \"low\" | Safety: \"low\" or \"high\" |\n\n**Color options:** `black_and_white`, `black`, `white`, `yellow`, `orange`, `red`, `purple`, `magenta`, `green`, `teal`, `blue`\n\n**Example:**\n```\nsearch_photos(\"mountain sunset\", per_page=5, orientation=\"landscape\")\n```\n\n### `get_random_photos`\n\nGet random photos, optionally filtered by keyword.\n\n**Parameters:**\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `query` | string | null | Optional keyword filter |\n| `count` | int | 1 | Number of photos (1-30) |\n| `orientation` | string | null | \"landscape\", \"portrait\", \"squarish\" |\n| `content_filter` | string | \"low\" | Safety: \"low\" or \"high\" |\n\n**Example:**\n```\nget_random_photos(query=\"nature\", count=3, orientation=\"landscape\")\n```\n\n### `track_download`\n\nTrack a photo download (required by Unsplash API guidelines).\n\n**Parameters:**\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `photo_id` | string | Photo ID from search results |\n\n**Example:**\n```\ntrack_download(\"abc123xyz\")\n```\n\n## Response Format\n\nEach photo includes:\n\n```python\n{\n    \"id\": \"abc123\",\n    \"description\": \"A beautiful mountain landscape\",\n    \"alt_description\": \"snow-capped mountains under blue sky\",\n    \"urls\": {\n        \"raw\": \"https://images.unsplash.com/...\",\n        \"full\": \"https://images.unsplash.com/...\",\n        \"regular\": \"https://images.unsplash.com/...\",  # Recommended for web\n        \"small\": \"https://images.unsplash.com/...\",\n        \"thumb\": \"https://images.unsplash.com/...\"\n    },\n    \"width\": 4000,\n    \"height\": 3000,\n    \"color\": \"#a3c4f3\",  # Dominant color for placeholders\n    \"blur_hash\": \"LKO2?U%2Tw=w...\",  # For progressive loading\n\n    # Attribution (REQUIRED when using the image)\n    \"photographer_name\": \"John Doe\",\n    \"photographer_username\": \"johndoe\",\n    \"photographer_url\": \"https://unsplash.com/@johndoe?utm_source=...\",\n    \"photo_url\": \"https://unsplash.com/photos/abc123?utm_source=...\",\n\n    # Ready-to-use attribution\n    \"attribution_text\": \"Photo by John Doe on Unsplash\",\n    \"attribution_html\": \"Photo by \u003ca href=\\\"...\\\"\u003eJohn Doe\u003c/a\u003e on \u003ca href=\\\"...\\\"\u003eUnsplash\u003c/a\u003e\"\n}\n```\n\n## Usage Example\n\nWhen an LLM builds a content page:\n\n1. Search for relevant images:\n   ```\n   photos = search_photos(\"coffee shop interior\", per_page=5)\n   ```\n\n2. Select a photo and use it:\n   ```html\n   \u003cimg src=\"{photo.urls.regular}\" alt=\"{photo.alt_description}\"\u003e\n   \u003cp class=\"attribution\"\u003e{photo.attribution_html}\u003c/p\u003e\n   ```\n\n3. If offering download, track it:\n   ```\n   download_url = track_download(photo.id)\n   ```\n\n## Unsplash API Guidelines\n\nThis server helps you comply with [Unsplash API guidelines](https://unsplash.com/api-terms):\n\n1. **Attribution** - Always credit the photographer and Unsplash (use `attribution_html`)\n2. **Hotlinking** - Use the provided URLs directly (enables view tracking)\n3. **Download tracking** - Call `track_download()` when users download images\n\n## Rate Limits\n\n- **Demo mode**: 50 requests/hour\n- **Production**: 5,000 requests/hour (after approval)\n\n## License\n\nMIT License - See [LICENSE](LICENSE) file.\n\n## Contributing\n\nContributions welcome! Please feel free to submit a Pull Request.\n\n## Support\n\nIf you find this project useful, consider buying me a coffee!\n\n\u003ca href=\"https://www.buymeacoffee.com/cevatkerim\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\" alt=\"Buy Me A Coffee\" style=\"height: 60px !important;width: 217px !important;\" \u003e\u003c/a\u003e\n\n## Acknowledgments\n\n- [Unsplash](https://unsplash.com) for providing an amazing free photo API\n- [FastMCP](https://github.com/jlowin/fastmcp) for the MCP server framework\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcevatkerim%2Funsplash-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcevatkerim%2Funsplash-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcevatkerim%2Funsplash-mcp/lists"}