Unsplash Mcp

Unsplash MCP サーバー

Unsplash から写真を適切なクレジット表記付きで取得するための MCP（Model Context Protocol）サーバーです。適切にクレジットされた画像を必要とするコンテンツページを構築する LLM 向けに設計されています。

機能

• 写真検索 - キーワードで写真を検索し、フィルター（色、向き）を適用できます
• ランダム写真 - コンテンツに変化を持たせるためのランダムな写真を取得できます
• ダウンロード追跡 - Unsplash API ガイドラインに準拠しています
• 完全なクレジット表記 - すべての写真にすぐに使えるクレジット表記テキストと HTML が含まれます
• LLM に最適化 - 埋め込みやすいよう整形済みのクレジット表記文字列を提供します

このサーバーが必要な理由

Unsplash の写真を使用する際には、適切なクレジット表記が求められます。このサーバーは以下を含めることでそれを簡単にします:

• attribution_text: 「Photo by John Doe on Unsplash」のようなプレーンテキスト
• attribution_html: Web ページ用の適切なリンクを含む完全な HTML

Photo by <a href="https://unsplash.com/@johndoe">John Doe</a> on <a href="https://unsplash.com">Unsplash</a>

インストール

前提条件

• Python 3.11 以上
• Unsplash API アクセスキー（こちらで取得）

クイックスタート

# Clone the repository
git clone https://github.com/cevatkerim/unsplash-mcp.git
cd unsplash-mcp

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install fastmcp httpx python-dotenv

# Set your API key
echo "UNSPLASH_ACCESS_KEY=your_key_here" > .env

# Run the server
fastmcp run server.py

設定

Claude Code

~/.claude.json（ユーザーレベル）またはプロジェクトの .mcp.json に追加します:

{
  "mcpServers": {
    "unsplash": {
      "type": "stdio",
      "command": "/path/to/unsplash-mcp/.venv/bin/fastmcp",
      "args": ["run", "/path/to/unsplash-mcp/server.py"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_access_key_here"
      }
    }
  }
}

Cursor

Cursor の MCP 設定に追加します:

{
  "mcpServers": {
    "unsplash": {
      "command": "/path/to/unsplash-mcp/.venv/bin/fastmcp",
      "args": ["run", "/path/to/unsplash-mcp/server.py"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_access_key_here"
      }
    }
  }
}

Windsurf / Cline

MCP 設定に追加します:

{
  "unsplash": {
    "command": "/path/to/unsplash-mcp/.venv/bin/fastmcp",
    "args": ["run", "/path/to/unsplash-mcp/server.py"],
    "env": {
      "UNSPLASH_ACCESS_KEY": "your_access_key_here"
    }
  }
}

ツール

search_photos

キーワードで写真を検索します。任意のフィルターを指定できます。

パラメーター:

パラメーター	型	デフォルト	説明
query	string	必須	検索キーワード
page	int	1	ページ番号
per_page	int	10	1 ページあたりの件数（1〜30）
order_by	string	"relevant"	並び順: "relevant" または "latest"
color	string	null	色フィルター（下記参照）
orientation	string	null	"landscape"、"portrait"、"squarish"
content_filter	string	"low"	安全性: "low" または "high"

色のオプション: black_and_white、black、white、yellow、orange、red、purple、magenta、green、teal、blue

例:

search_photos("mountain sunset", per_page=5, orientation="landscape")

get_random_photos

ランダムな写真を取得します。任意でキーワードによるフィルターを指定できます。

パラメーター:

パラメーター	型	デフォルト	説明
query	string	null	任意のキーワードフィルター
count	int	1	写真の件数（1〜30）
orientation	string	null	"landscape"、"portrait"、"squarish"
content_filter	string	"low"	安全性: "low" または "high"

例:

get_random_photos(query="nature", count=3, orientation="landscape")

track_download

写真のダウンロードを追跡します（Unsplash API ガイドラインで必須）。

パラメーター:

パラメーター	型	説明
photo_id	string	検索結果から取得した写真 ID

例:

track_download("abc123xyz")

レスポンス形式

各写真には以下が含まれます:

{
    "id": "abc123",
    "description": "A beautiful mountain landscape",
    "alt_description": "snow-capped mountains under blue sky",
    "urls": {
        "raw": "https://images.unsplash.com/...",
        "full": "https://images.unsplash.com/...",
        "regular": "https://images.unsplash.com/...",  # Recommended for web
        "small": "https://images.unsplash.com/...",
        "thumb": "https://images.unsplash.com/..."
    },
    "width": 4000,
    "height": 3000,
    "color": "#a3c4f3",  # Dominant color for placeholders
    "blur_hash": "LKO2?U%2Tw=w...",  # For progressive loading

    # Attribution (REQUIRED when using the image)
    "photographer_name": "John Doe",
    "photographer_username": "johndoe",
    "photographer_url": "https://unsplash.com/@johndoe?utm_source=...",
    "photo_url": "https://unsplash.com/photos/abc123?utm_source=...",

    # Ready-to-use attribution
    "attribution_text": "Photo by John Doe on Unsplash",
    "attribution_html": "Photo by <a href=\"...\">John Doe</a> on <a href=\"...\">Unsplash</a>"
}

使用例

LLM がコンテンツページを構築する場合:

1. 関連する画像を検索します:

   photos = search_photos("coffee shop interior", per_page=5)
   

2. 写真を選択して使用します:

   <img src="{photo.urls.regular}" alt="{photo.alt_description}">
   <p class="attribution">{photo.attribution_html}</p>
   

3. ダウンロードを提供する場合は、それを追跡します:

   download_url = track_download(photo.id)
   

Unsplash API ガイドライン

このサーバーは Unsplash API ガイドライン への準拠を支援します:

1. クレジット表記 - 常に撮影者と Unsplash をクレジットしてください（attribution_html を使用）
2. ホットリンク - 提供された URL を直接使用してください（ビューの追跡が有効になります）
3. ダウンロード追跡 - ユーザーが画像をダウンロードしたときに track_download() を呼び出してください

レート制限

• デモモード: 1 時間あたり 50 リクエスト
• 本番環境: 1 時間あたり 5,000 リクエスト（承認後）

ライセンス

MIT ライセンス - LICENSE ファイルをご覧ください。

コントリビューション

コントリビューションを歓迎します！お気軽に Pull Request を送ってください。

サポート

このプロジェクトが役に立ったと思ったら、コーヒーをご馳走いただけると嬉しいです！

謝辞

• 素晴らしい無料の写真 API を提供している Unsplash
• MCP サーバーフレームワークを提供している FastMCP