Unsplash MCP · by pixlib

Photos for
Claude,
on demand.

A remote MCP server that connects Claude to Unsplash. Claude searches millions of free photos, gets back hotlinked image URLs, and receives ready-to-use photographer attribution with every result — no API key setup on your end.

Railway · hosted Streamable HTTP Unsplash API Attribution built-in unsplash.pixlib.app · live
Add custom connector → https://unsplash.pixlib.app/mcp
Streamable HTTP · Unsplash API · unsplash.pixlib.app
3
MCP tools exposed
5
Image sizes per photo
100%
Photos attributed
0
Personal data stored
HTTP
Streamable transport

Tools

three, read + side-effect
search_photos read-only

Search Unsplash by keyword with optional filters. Returns photos with hotlinked CDN URLs and attribution strings.

query   string
orientation   landscape | portrait | squarish
color   black_and_white | blue | …
per_page   1–30
get_random_photos read-only

Fetch random photos, optionally filtered by keyword — ideal for hero images and backgrounds where you want variety.

query   string (optional)
count   1–30
orientation   landscape | portrait | squarish
track_download side-effect

Registers a download event with Unsplash — required by their API guidelines whenever a photo is saved or used. Returns the full-resolution URL.

photo_id   string

Examples

real tool calls
search_photos
Call
search_photos(query="mountain
landscape", per_page=3,
orientation="landscape")
Returns
3 photos
Photo by simon on Unsplash
images.unsplash.com/…
get_random_photos
Call
get_random_photos(
query="modern office",
count=2)
Returns
2 random photos
Photo by Yosh Ginsu on Unsplash
+ attribution_html
track_download
Call
track_download(
photo_id="Q5dMq3cKqec")
Returns
https://images.unsplash.com/
…/download URL
+ event registered

Architecture

how it connects
Claude
Adds the connector by URL. Streamable HTTP transport — no API key, no per-user setup.
unsplash.pixlib.app
FastMCP server on Railway. Stateless, per-IP rate limited. Holds the Unsplash key server-side.
Unsplash API
Photo search, random, and download endpoints. Results hotlinked from the Unsplash CDN.
Every response carries
attribution_text — "Photo by … on Unsplash" attribution_html — linked, UTM-tagged urls — raw / full / regular / small / thumb

Stack

lean by design
FastMCP
MCP server framework (Python)
Streamable HTTP at /mcp
httpx
Async client for the Unsplash API
api.unsplash.com
Railway
Container host, Dockerfile build
unsplash.pixlib.app · port 8080
Unsplash API
Photo source · registered app
pixlib(claude mcp)
Python 3.12
Runtime · slim image
requires-python >= 3.11
Porkbun
Registrar for pixlib.app
CNAME → Railway · SSL via Railway

Unsplash API Compliance

guidelines, handled

Attribution

Every photo includes attribution_text and attribution_html that credit the photographer and Unsplash, with UTM-tagged links back to both (utm_source=pixlib_claude_mcp).

Hotlinking

Image URLs point directly at the Unsplash CDN (images.unsplash.com). Photos are never re-hosted or cached, which preserves Unsplash's view tracking.

Download tracking

The track_download tool triggers Unsplash's download endpoint whenever a photo is used, as their API guidelines require.

Not affiliated with Unsplash, Inc. Photos and the Unsplash name are provided by Unsplash under the Unsplash API Terms.

Code

server.py — attribution builder
server.py
# Built for every photo, so attribution is never optional
def _photo_to_dataclass(photo: dict) -> UnsplashPhoto:
  user = photo["user"]
  name = user.get("name", user["username"])
  utm = "pixlib_claude_mcp"  # matches the registered app
  profile = f"https://unsplash.com/@{user['username']}" \
          f"?utm_source={utm}&utm_medium=referral"
  return UnsplashPhoto(
    urls=photo["urls"],  # raw / full / regular / small / thumb
    attribution_text=f"Photo by {name} on Unsplash",
    attribution_html=_html(name, profile, utm),
    …
  )

# Download trigger — required by Unsplash guidelines
@mcp.tool(title="Track Unsplash Photo Download")
async def track_download(photo_id: str) -> str:
  r = await client.get(f"{BASE}/photos/{photo_id}/download")
  return r.json()["url"]

Privacy Policy

Last updated June 27, 2026

What we collect

Nothing that identifies you. No account, login, or email required. The only transient data is an in-memory, per-IP rate-limit counter that resets hourly and is never written to disk.

How it's used

Your search terms are forwarded to the Unsplash API to fetch photo results. Queries are not logged, analyzed, or stored by this service.

Third parties

Search terms reach Unsplash (governed by their privacy policy). Hosting is on Railway, which may retain infrastructure logs.

Contact

Questions or requests: ninavolu7@gmail.com or open an issue on GitHub.

Full Privacy Policy

Last updated: June 27, 2026

1. Information we collect

This server does not collect, store, or process personally identifiable information. No registration, email, name, or login is required. The only transient data is a rate-limit counter keyed to your IP address, held in memory only, never written to disk, and reset on server restart.

2. How your data is used

Search and query parameters sent through the MCP tools are forwarded to the Unsplash API to retrieve photo results. These queries are not logged, analyzed, or stored by this service. Unsplash's handling of that data is governed by their policy at unsplash.com/privacy.

3. Cookies and tracking

This service sets no cookies and uses no analytics, tracking pixels, or fingerprinting.

4. Data retention

No user data is retained. The service is stateless beyond the in-memory, per-IP rate-limit counter described above.

5. Third-party services

  • Unsplash API — photo search results and download tracking. Subject to Unsplash's privacy policy and API Terms.
  • Railway — cloud hosting. May retain infrastructure-level logs per their own policy.

6. Children's privacy

This service is not directed at children under 13 and does not knowingly collect data from minors.

7. Changes to this policy

Updates are reflected on this page with a revised date. Continued use constitutes acceptance of the updated policy.

8. Contact

Data questions or deletion requests: ninavolu7@gmail.com, or open an issue at github.com/ninavolu/unsplash-mcp.