Unsplash MCP Server

Unsplash MCP サーバー

Unsplash の写真検索と取得機能を提供する Model Context Protocol サーバーです。このサーバーを使用すると、LLM は Unsplash の膨大なコレクションから写真を検索、取得したり、ランダムな写真を取得したりできます。これは Go で実装されており、search_photos、get_photo、random_photo などのツールを提供します。

✨ 機能

• 高度な画像検索：次のフィルターを使って、Unsplash の膨大な写真ライブラリを検索できます。
  • キーワードの関連性
  • 配色
  • 向きのオプション
  • カスタムの並べ替えとページネーション
• 詳細な写真情報：EXIF データ、撮影場所、写真家の情報など、特定の写真について包括的な詳細を取得できます。
• ランダムな写真の選択：柔軟なフィルターオプションを使って、ランダムな写真を取得できます。
• 複数の接続モード：
  • LLM と直接統合するための標準入出力モード
  • Web ベースの接続用の Server-Sent Events（SSE）モード

利用可能なツール

• search_photos - Unsplash で写真を検索します

  • query（string、必須）：検索キーワード
  • page（number、任意）：ページ番号（1 始まり）、デフォルト：1
  • per_page（number、任意）：1 ページあたりの結果数（1～30）、デフォルト：10
  • order_by（string、任意）：並べ替え方法（relevant または latest）、デフォルト："relevant"
  • color（string、任意）：色フィルター（black_and_white、black、white、yellow、orange、red、purple、magenta、green、teal、blue）
  • orientation（string、任意）：向きのフィルター（landscape、portrait、squarish）

• get_photo - 特定の写真について詳細情報を取得します

  • photoId（string、必須）：取得する写真の ID

• random_photo - 1 枚以上のランダムな写真を取得します

  • count（number、任意）：返す写真の枚数（デフォルト：1、最大：30）
  • collections（string、任意）：選択を絞り込むための公開コレクション ID。複数指定する場合はカンマ区切り
  • topics（string、任意）：選択を絞り込むための公開トピック ID。複数指定する場合はカンマ区切り
  • username（string、任意）：選択対象を特定のユーザーに限定します
  • query（string、任意）：検索語に一致する写真に選択対象を限定します
  • orientation（string、任意）：写真の向きで絞り込みます。有効な値：landscape、portrait、squarish
  • content_filter（string、任意）：コンテンツの安全性で結果を絞り込みます。有効な値：low、high
  • featured（boolean、任意）：選択対象を注目の写真に限定します

インストール

オプション 1：ビルド済みバイナリをダウンロード

お使いのプラットフォーム向けの最新のビルド済みバイナリを GitHub リリースページからダウンロードし、以下のインストール手順に従ってください。

# Download the arm64 version
curl -L https://github.com/okooo5km/unsplash-mcp-server-go/releases/latest/download/unsplash-mcp-server-macos-arm64.zip -o unsplash-mcp-server.zip
unzip unsplash-mcp-server.zip
chmod +x unsplash-mcp-server

# Remove quarantine attribute to avoid security warnings
xattr -d com.apple.quarantine unsplash-mcp-server

# Install to your local bin directory
mkdir -p ~/.local/bin
mv unsplash-mcp-server ~/.local/bin/
rm unsplash-mcp-server.zip

# Download the x86_64 version
curl -L https://github.com/okooo5km/unsplash-mcp-server-go/releases/latest/download/unsplash-mcp-server-macos-x86_64.zip -o unsplash-mcp-server.zip
unzip unsplash-mcp-server.zip
chmod +x unsplash-mcp-server

# Remove quarantine attribute to avoid security warnings
xattr -d com.apple.quarantine unsplash-mcp-server

# Install to your local bin directory
mkdir -p ~/.local/bin
mv unsplash-mcp-server ~/.local/bin/
rm unsplash-mcp-server.zip

# Download the universal version
curl -L https://github.com/okooo5km/unsplash-mcp-server-go/releases/latest/download/unsplash-mcp-server-macos-universal.zip -o unsplash-mcp-server.zip
unzip unsplash-mcp-server.zip
chmod +x unsplash-mcp-server

# Remove quarantine attribute to avoid security warnings
xattr -d com.apple.quarantine unsplash-mcp-server

# Install to your local bin directory
mkdir -p ~/.local/bin
mv unsplash-mcp-server ~/.local/bin/
rm unsplash-mcp-server.zip

# Download the amd64 version
curl -L https://github.com/okooo5km/unsplash-mcp-server-go/releases/latest/download/unsplash-mcp-server-linux-amd64.tar.gz -o unsplash-mcp-server.tar.gz
tar -xzf unsplash-mcp-server.tar.gz
chmod +x unsplash-mcp-server

# Install to your local bin directory
mkdir -p ~/.local/bin
mv unsplash-mcp-server ~/.local/bin/
rm unsplash-mcp-server.tar.gz

# Download the arm64 version
curl -L https://github.com/okooo5km/unsplash-mcp-server-go/releases/latest/download/unsplash-mcp-server-linux-arm64.tar.gz -o unsplash-mcp-server.tar.gz
tar -xzf unsplash-mcp-server.tar.gz
chmod +x unsplash-mcp-server

# Install to your local bin directory
mkdir -p ~/.local/bin
mv unsplash-mcp-server ~/.local/bin/
rm unsplash-mcp-server.tar.gz

インストールディレクトリが PATH に含まれていることを確認してください。

• macOS/Linux：シェル設定ファイル（.bashrc、.zshrc など）にexport PATH="$HOME/.local/bin:$PATH"を追加します
• Windows：システムのプロパティ > 環境変数のダイアログから、ディレクトリをシステム PATH に追加します

オプション 2：ソースからビルドする

1. リポジトリをクローンします。

   git clone https://github.com/okooo5km/unsplash-mcp-server-go.git
   cd unsplash-mcp-server-go
   

2. プロジェクトをビルドします。

   Make を使用（推奨）：

   # Build for your current platform
   make
   
   # Or build for a specific platform
   make build-darwin-universal    # macOS Universal Binary
   make build-darwin-arm64        # macOS Apple Silicon
   make build-darwin-amd64        # macOS Intel
   make build-linux-amd64         # Linux x86_64
   make build-linux-arm64         # Linux ARM64
   make build-windows-amd64       # Windows x86_64
   
   # Or build for all platforms at once
   make build-all
   
   # Create distribution packages for all platforms
   make dist
   

   バイナリは.buildディレクトリに配置されます。

   Go を直接使用：

   go build -o unsplash-mcp-server
   

3. バイナリをインストールします。

   # Install to user directory (recommended, no sudo required)
   mkdir -p ~/.local/bin
   cp unsplash-mcp-server ~/.local/bin/
   

   シェル設定ファイルに追加して、~/.local/binが PATH に含まれていることを確認してください。

   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc  # or ~/.bashrc
   source ~/.zshrc  # or source ~/.bashrc
   

設定

環境変数

サーバーを動作させるには、Unsplash API アクセスキーが必要です。環境に設定してください。

export UNSPLASH_ACCESS_KEY="your-access-key-here"

• Unsplash API アクセスキー（Unsplash Developers Portalで登録してください）

Unsplash API アクセスキーの取得

1. Unsplash Developers Portalにアクセスします
2. Unsplash アカウントに登録するか、ログインします
3. 新しいアプリケーションを登録します
4. API の使用条件とガイドラインに同意します
5. アプリケーションの詳細（名前、説明など）を入力します
6. 登録が完了すると、アクセスキー（クライアント ID とも呼ばれます）が発行されます

Claude.app の設定

Claude の設定に追加します。

"mcpServers": {
  "unsplash": {
    "command": "unsplash-mcp-server",
    "env": {
      "UNSPLASH_ACCESS_KEY": "your-access-key-here"
    }
  }
}

Cursor の設定

次の設定を Cursor エディターのsettings.jsonに追加します。

{
  "mcpServers": {
    "unsplash": {
      "command": "unsplash-mcp-server",
      "env": {
        "UNSPLASH_ACCESS_KEY": "your-access-key-here"
      }
    }
  }
}

Chatwise の設定

注：Chatwise で環境変数を追加するときは、値を引用符で囲まないでください（#1を修正）。

コマンドライン引数

サーバーは次のコマンドライン引数に対応しています。

• -h, --help：サーバーのヘルプ情報、使用方法、利用可能なオプションを表示します
• -v, --version：unsplash-mcp-server のバージョン番号を表示します
• -t, --transport <string>：使用するトランスポートの種類（デフォルト："stdio"）
  • stdio：LLM と直接連携するための標準入力／出力モード
  • sse：ウェブベースの接続用の Server-Sent Events モード
• -p, --port <int>：SSE モードで実行するときに使用するポート（デフォルト：8080）

使用例：

# Display help information
unsplash-mcp-server --help

# Display version information
unsplash-mcp-server --version

# Start server with default settings (stdio mode)
unsplash-mcp-server

# Start server in SSE mode on the default port (8080)
unsplash-mcp-server --transport sse

# Start server in SSE mode on a custom port
unsplash-mcp-server --transport sse --port 9090

SSE モードで実行すると、指定したポートでサーバーに HTTP 経由でアクセスでき、ウェブベースのクライアントが接続できます。デフォルトの stdio モードでは、サーバーは標準入力／出力を介して通信します。これは LLM アプリケーションとの直接連携に適しています。

システムプロンプトの例

次のシステムプロンプトを使用すると、Claude が unsplash-mcp-server を効果的に利用できるようになります。

You have access to Unsplash photo search tools through MCP. You can:

1. Search for photos using specific keywords, colors, or orientations:
   - Use the search_photos tool to find images on any topic
   - Filter by color or orientation as needed
   - You can page through results and control how many appear per page

2. Get detailed information about specific photos:
   - Use get_photo with a photo ID to retrieve comprehensive details
   - This includes EXIF data, location info, and photographer details

3. Fetch random photos with customizable filters:
   - Use random_photo tool to get surprise images based on criteria
   - Filter random selections by topic, collection, username, etc.

When the user asks for images, use these tools to find relevant Unsplash photos.
Include photo URLs in your responses so users can view the images.

開発要件

• Go 1.20 以降
• Unsplash API アクセスキー
• MCP Go SDK 0.19.0 以降

使用例

写真を検索する

{
  "query": "mountain landscape",
  "per_page": 5,
  "color": "blue",
  "orientation": "landscape"
}

写真の詳細を取得する

{
  "photoId": "Dwu85P9SOIk"
}

ランダムな写真を取得する

{
  "count": 3,
  "query": "coffee",
  "orientation": "portrait"
}

バージョン履歴

バージョン履歴と変更履歴については、GitHub Releases をご覧ください。

☕️ プロジェクトを応援する

unsplash-mcp-server が役に立った場合は、開発への支援をご検討ください。

• ⭐️ GitHub でプロジェクトにスターを付ける
• 🐛 Issue トラッカーでバグを報告したり、機能を提案したりする
• 🔄 コードの改善に役立つプルリクエストを送信する
• 💝 次の方法で支援する：

unsplash-mcp-server-go は MIT License のもとでライセンスされています。これは、MIT License の条項および条件に従うことを条件に、このソフトウェアを自由に使用、変更、配布できることを意味します。詳細については、プロジェクトリポジトリ内の LICENSE ファイルをご覧ください。