convez.ai
MCP Server
atomicpages

unsplash-mcp

atomicpages/unsplash-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

A dual-transport MCP server for Unsplash.com

Instalação

$npx convez-ai atomicpages/unsplash-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v1.0.1
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

unsplashed-mcp

MCP server for the Unsplash photo API. 12 tools for searching photos, browsing collections, exploring topics, and discovering photographers.

Why?

  • Other Unsplash MCP servers expose a single tool. This exposes 12 to handle common API calls, plus some extra goodies.
  • Supports rate-limiting based on your limits
  • Supports dual-transports
  • Supports TLS via env vars

Usage

Designing and developing UIs. This is a great addition to your toolkit for injecting beautiful stock images. I plugged this into cursor while building a Shopify template for a store and it works great.

Requires Bun and an Unsplash access key.

Quick Start

No clone needed. Run directly with bunx:

UNSPLASH_ACCESS_KEY=your_key bunx unsplashed-mcp

Cursor / Claude Desktop

Add to your MCP settings (~/.cursor/mcp.json or workspace .cursor/mcp.json):

{
  "mcpServers": {
    "unsplash": {
      "command": "bunx",
      "args": ["@mcpcraft/unsplash-mcp"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_access_key_here"
      }
    }
  }
}

HTTP (multi-tenant, stateless)

UNSPLASH_ACCESS_KEY=your_key TRANSPORT=http bunx @mcpcraft/unsplash-mcp

Listens on http://localhost:3000/mcp. Clients pass their Unsplash key as a Bearer token:

Authorization: Bearer <unsplash_access_key>

HTTP Configuration

TLS

Credentials must not travel in cleartext. Two options:

Direct TLS:

TLS_CERT_FILE=/path/to/cert.pem TLS_KEY_FILE=/path/to/key.pem TRANSPORT=http bun src/index.ts

Reverse proxy (recommended):

nginx:

server {
    listen 443 ssl;
    server_name mcp.example.com;

    ssl_certificate     /etc/ssl/certs/mcp.pem;
    ssl_certificate_key /etc/ssl/private/mcp.key;

    location /mcp {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Caddy:

mcp.example.com {
    reverse_proxy /mcp localhost:3000
}

Ngrok:

ngrok http http://localhost:3000

Cloudflare Tunnel:

cloudflared tunnel --url http://localhost:3000

Rate Limiting

Per-key rate limiting enforced in HTTP mode. Defaults to 50 req/hr (Unsplash demo tier). Set higher for production-approved apps (max 5000):

export RATE_LIMIT_PER_HOUR=1000
export TRANSPORT=http
bun src/index.ts

Environment Variables

VariableDefaultDescription
UNSPLASH_ACCESS_KEY—Required for stdio mode
TRANSPORTstdiostdio or http
PORT3000HTTP listen port
TLS_CERT_FILE—Path to TLS certificate
TLS_KEY_FILE—Path to TLS private key
RATE_LIMIT_PER_HOUR50Per-key rate limit (1–5000)

Tools

ToolDescription
unsplash_search_photosSearch photos by keyword with filters (color, orientation, order)
unsplash_search_collectionsSearch photo collections by keyword
unsplash_search_usersSearch photographers by name or username
unsplash_get_photoGet full photo details (EXIF, location, tags, URLs)
unsplash_random_photoGet random photos with optional filters
unsplash_list_photosBrowse the editorial photo feed
unsplash_track_downloadTrack a photo download (required by Unsplash API guidelines)
unsplash_get_userGet a photographer's public profile
unsplash_list_topicsBrowse curated photo topics
unsplash_get_topic_photosGet photos for a specific topic
unsplash_photographer_portfolio360 view: profile + photos + collections + stats (4 parallel calls)
unsplash_collection_overviewFull collection: details + photos + related (3 parallel calls)

Development

git clone https://github.com/atomicpages/unsplash-mcp.git
cd unsplashed-mcp
bun install
cp .env.example .env   # add your UNSPLASH_ACCESS_KEY
bun start        # Run from source (stdio)
bun test         # Run tests
bun codegen      # Regenerate API client from OpenAPI spec
bun typecheck    # Type-check
bun lint         # Lint

MCP Inspector

bun mcp
Ver o original no GitHub

Relacionados