Unsplash MCP Server

Unsplash MCP Server

このプロジェクトは、Unsplash API と連携するツールを提供する Model Context Protocol（MCP）サーバーを実装しており、写真の検索やダウンロードができます。

(注：必要に応じて、@shariqriazz を正しいユーザー名／名前空間に置き換えてください)

Git リポジトリ： https://github.com/shariqriazz/upsplash-mcp-server (正しい URL でない場合は更新してください)

機能

• Unsplash API と連携する MCP ツールを提供します。
• クエリ、ページネーション、向きに基づいて写真を検索します。
• 指定した解像度（raw、full、regular、small）で写真をダウンロードします。
• 環境変数で設定した Unsplash アクセスキーが必要です。
• ワークスペース内のローカル unsplash/ ディレクトリに写真をダウンロードします。

提供するツール

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

  • 入力スキーマ：

    {
      "type": "object",
      "properties": {
        "query": { "type": "string", "description": "The search term(s)." },
        "page": { "type": "number", "description": "Page number (default: 1).", "default": 1 },
        "per_page": { "type": "number", "description": "Items per page (default: 10, max: 30).", "default": 10, "maximum": 30 },
        "orientation": { "type": "string", "enum": ["landscape", "portrait", "squarish"], "description": "Filter by orientation." }
      },
      "required": ["query"]
    }
    

  • **出力：**検索結果を含む JSON データと、画像リンクを含む書式付きテキストの要約を返します。

• download_photo：ダウンロード追跡イベントを発生させた後、Unsplash の写真をワークスペースの unsplash/ フォルダーにダウンロードします。

  • 入力スキーマ：

    {
      "type": "object",
      "properties": {
        "photo_id": { "type": "string", "description": "The ID of the photo to download." },
        "resolution": { "type": "string", "enum": ["raw", "full", "regular", "small"], "description": "Desired resolution (default: raw).", "default": "raw" },
        "filename": { "type": "string", "description": "Optional filename (e.g., my-image.jpg). Defaults to sanitized description or {photo_id}.jpg." }
      },
      "required": ["photo_id"]
    }
    

  • **出力：**ダウンロードしたファイルのパスを含む成功メッセージを返します。

(注：スキーマは説明用です。サーバーは MCP を通じて正確なスキーマを公開します。)

前提条件

• Node.js（v18+ 推奨）
• Bun（npm install -g bun）
• Unsplash アカウントと API アクセスキー（https://unsplash.com/developers）

セットアップとインストール

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

   git clone https://github.com/shariqriazz/upsplash-mcp-server.git # Update URL if needed
   cd upsplash-mcp-server
   

2. 依存関係をインストールします：

   bun install
   

3. 環境を設定します：
   • プロジェクトのルートに .env ファイルを作成します（または、用意されている場合は .env.example をコピーします）。
   • Unsplash アクセスキーを追加します：

     UNSPLASH_ACCESS_KEY="YOUR_UNSPLASH_ACCESS_KEY"
     

4. サーバーをビルドします：

   bun run build
   

   これにより、TypeScript コードが build/index.js にコンパイルされます。

使用方法（スタンドアロン／NPX）

スタンドアロン（ローカルビルド）：

コンパイル済みのサーバーは、bun または node を使って直接実行できます。シェルまたは .env ファイルで UNSPLASH_ACCESS_KEY 環境変数が設定されていることを確認してください。

# Ensure UNSPLASH_ACCESS_KEY is set
bun run build/index.js
# OR
node build/index.js

NPX を使用する場合（npm に公開されている場合）：

このパッケージが npm（例：unsplash-mcp-server）に公開されていれば、npx を使って直接実行できます。

# Ensure UNSPLASH_ACCESS_KEY is set in your environment
npx -y unsplash-mcp-server

注：これには、指定した名前で npm にパッケージが公開されている必要があります。

Cline での実行

1. MCP 設定を構成する： Cline の MCP 設定ファイル（例：.roo/mcp.json またはグローバル設定）に設定を追加または更新します。主な方法は次の 2 つです。

   オプション A：Bun/Node を使用する（直接パス - ローカル開発におすすめ）

   この方法では、bun（または node）を使用して、ローカルのプロジェクトディレクトリにあるコンパイル済みスクリプトを直接実行します。

   {
     "mcpServers": {
       "unsplash-mcp-server": {
         "command": "bun", // または "node"
         "args": [
           // プロジェクト内のコンパイル済み index.js の絶対パスを指定します
           "/path/to/your/upsplash-mcp-server/build/index.js"
         ],
         "env": {
           // 必須：.env と一致させるか、ここで設定してください
           "UNSPLASH_ACCESS_KEY": "YOUR_UNSPLASH_ACCESS_KEY" // 実際のキーに置き換えてください
         },
         "disabled": false,
         "alwaysAllow": [
            "search_photos",
            "download_photo"
            // "trigger_download" // このツールが存在し、個別に使用できる場合は含めてください
         ],
         "timeout": 3600 // 任意：タイムアウト（秒）（例：1 時間）
       }
       // 他のサーバーをここに追加します...
     }
   }
   

   • 重要： /path/to/your/upsplash-mcp-server/build/index.js を、システム上の正しい絶対パスに置き換えてください。
   • "YOUR_UNSPLASH_ACCESS_KEY" を実際のキーに置き換えてください。実際の JSON ファイルからコメントを削除してください。

   オプション B：NPX を使用する（npm へのパッケージ公開が必要）

   この方法では、npx を使用して npm レジストリからサーバーパッケージを自動的にダウンロードし、実行します。リポジトリをローカルにクローンしたくない場合や、公開済みのバージョンを使いたい場合に便利です。

   {
     "mcpServers": {
       "unsplash-mcp-server": {
         "command": "npx",
         "args": [
           "-y", // インストールを自動的に承認します
           "unsplash-mcp-server" // 想定される npm パッケージ名です。異なる場合は更新してください
         ],
         "env": {
           // 必須：ここまたは環境変数で設定してください
           "UNSPLASH_ACCESS_KEY": "YOUR_UNSPLASH_ACCESS_KEY" // 実際のキーに置き換えてください
         },
         "disabled": false,
         "alwaysAllow": [
            "search_photos",
            "download_photo"
         ],
         "timeout": 3600 // 任意：タイムアウト（秒）
       }
       // 他のサーバーをここに追加します...
     }
   }
   

   • env ブロックに必要な UNSPLASH_ACCESS_KEY が含まれていることを確認してください。
   • 公開済みの npm パッケージ名が異なる場合は、args 内の "unsplash-mcp-server" を更新してください。

2. Cline を再起動／再読み込みする： Cline は設定の変更を検出し、選択した方法に基づいてサーバーを起動します。

3. ツールを使用する： Cline を通じて search_photos および download_photo ツールを使用できるようになります。

開発

• 監視モード： bun run watch（通常、サーバーを起動し、ファイルの変更時に再起動します）
• Lint： bun run lint（コードのスタイルと潜在的なエラーをチェックします）
• フォーマット： bun run format（プロジェクトの標準に従ってコードをフォーマットします）

（注：標準的な package.json スクリプト（watch、lint、format など）を想定しています。スクリプトが異なる場合は更新してください。）

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細については LICENSE ファイルを参照してください。