🖼️ Unsplash Smart MCP Server

🖼️ Unsplash Smart MCP Server

手間をかけずに、AI エージェントに美しいビジュアルを。

AI エージェントが、インテリジェントなコンテキスト認識と自動帰属管理により、Unsplash のプロ品質のストックフォトをシームレスに検索、推薦、提供できる強力な FastMCP サーバーです。

🚀 この Unsplash 統合を選ぶ理由

ビジュアルコンテンツ統合の分野において、この Unsplash Smart MCP Server は、AI を活用した画像取得の決定版ソリューションとして際立っています。

• 🧠 AI エージェント向けに最適化：Cursor 上の Claude などの AI エージェント向けに構築され、自然言語での画像リクエストを効率化します
• 🔍 コンテキストを認識した画像選択：曖昧なリクエストをインテリジェントに解釈し、抽象的なプロンプトからでも関連性の高い画像を提供します
• ⚡ 単一ツールによる効率化：画像ワークフロー全体を処理する統合された stock_photo ツールにより、ツールの乱立を防ぎます
• 📊 リソースの最適化：URL を優先する方式により、柔軟性を保ちながら帯域幅とストレージを節約します
• ✅ 帰属表示を自動化：開発者の作業を一切必要とせず、Unsplash の利用規約への準拠を実現します
• 📁 プロジェクトを認識した整理：プロジェクト構成（Next.js、React、Vue など）に基づいて画像をインテリジェントに整理します
• 🧩 シームレスな統合：最小限のセットアップで、既存のワークフローと最大限に互換性を保つよう設計されています

✨ 比類ない機能

AI エージェント開発者向け

• コンテキストに応じたスマート検索：自然言語でリクエストして、最適な画像を見つけられます
• 被写体を自動選択：目的の説明から、AI が最適な画像の被写体を判断します
• 意図に基づく結果：キーワードだけでなく、その背景にある意図にも合致する画像を取得できます
• シームレスなエージェント統合：Cursor 上の Claude をはじめ、ほかの MCP 対応エージェントでもすぐに利用できます

プロジェクトの効率化

• 2 段階のワークフロー：制御されたダウンロードに使える URL を取得でき、権限の問題や不要なストレージ使用を回避します
• プロジェクトを認識したファイル管理：フレームワークの規約に基づいて画像を自動整理します
• ディレクトリをインテリジェントに作成：プロジェクトの種類に基づいて適切なフォルダー構成を作成します
• 段階的な拡張：手早いプロトタイプからエンタープライズアプリケーションまで、あらゆる規模のプロジェクトで利用できます

コンプライアンス面の安心

• 帰属表示を包括的に管理：
  • すべての画像の使用状況をローカルの帰属データベースで記録します
  • 写真家のメタデータを画像に自動的に埋め込みます（EXIF、IPTC、XMP）
  • 複数の形式で帰属表示ページをワンクリックで生成します
  • 帰属データ向けの包括的な API を提供します

🛠️ インストール

前提条件

• Node.js 18.x 以上
• Unsplash API アクセスキー（こちらから取得）

ローカルインストール（推奨）

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

git clone https://github.com/drumnation/unsplash-smart-mcp-server.git
cd unsplash-smart-mcp-server

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

npm install

3. Cursor の MCP 設定を構成します：

   • macOS：~/.cursor/mcp.json を編集します
   • Windows：%USERPROFILE%\.cursor\mcp.json を編集します
   • Linux：~/.cursor/mcp.json を編集します

4. 次の設定を追加します：

{
  "servers": {
    "unsplash": {
      "command": "npx",
      "args": ["tsx", "src/server.ts"],
      "cwd": "/absolute/path/to/unsplash-smart-mcp-server",
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_api_key_here"
      }
    }
  }
}

5. 次の内容を置き換えます：

   • /absolute/path/to/unsplash-smart-mcp-server をリポジトリをクローンした実際のパスに置き換えます
   • your_api_key_here を Unsplash API キーに置き換えます

6. ファイルを保存して、Cursor を再起動します。

重要： 多くの MCP サーバーとは異なり、このサーバーではプロセス間の直接パイプが必要です。FastMCP の I/O 処理方法のため、TCP ポート経由や npm から直接アクセスすることはできません。ローカルインストールが最も確実な方法です。

Cursor CLI を使う方法

Cursor の CLI を使用する場合：

claude mcp add unsplash npx tsx /path/to/unsplash-smart-mcp-server/src/server.ts --cwd /path/to/unsplash-smart-mcp-server
claude mcp config set unsplash UNSPLASH_ACCESS_KEY=your_api_key_here

パスと API キーを実際の値に置き換えてください。

Docker を使う方法（最も確実な方法）

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

git clone https://github.com/drumnation/unsplash-smart-mcp-server.git
cd unsplash-smart-mcp-server

2. docker-compose.yml ファイルを作成します：

services:
  unsplash-mcp:
    build: .
    image: unsplash-mcp-server
    restart: always
    stdin_open: true
    tty: true
    environment:
      - UNSPLASH_ACCESS_KEY=your_api_key_here

3. コンテナをビルドして起動します：

docker-compose up -d

4. Cursor の MCP 設定を構成します：

   • macOS：~/.cursor/mcp.json を編集します
   • Windows：%USERPROFILE%\.cursor\mcp.json を編集します
   • Linux：~/.cursor/mcp.json を編集します

5. 次の設定を追加します：

{
  "servers": {
    "unsplash": {
      "command": "docker",
      "args": ["exec", "-i", "unsplash-mcp-unsplash-mcp-1", "tsx", "src/server.ts"],
      "env": {}
    }
  }
}

6. ファイルを保存して、Cursor を再起動します。

この設定により、次のことが可能になります：

• Docker の起動時にサーバーが自動的に起動します
• クラッシュした場合、サーバーが再起動します
• ターミナルウィンドウを開かずにバックグラウンドで実行されます
• Cursor への安定した接続が提供されます

Smithery を使う方法（クラウドデプロイ）

クラウドにデプロイする場合は、Smithery を使用できます：

1. Smithery 経由で Cursor にサーバーをインストールします：

npx @smithery/cli install @drumnation/unsplash-smart-mcp-server --client cursor --key your_api_key_here

2. または、Smithery.ai にログインして、ウェブインターフェースからデプロイできます。

Windows ユーザーへの注意： Smithery でのデプロイには、Windows との互換性を確保するための特別な処理が含まれています。

詳しい手順とトラブルシューティングについては、Smithery デプロイガイドを参照してください。

🧩 AI エージェントとの統合

Cursor で Claude を使う手順

Unsplash Smart MCP Server は、AI エージェントを通じた画像取得を手軽で直感的に行えるように設計されています：

1. リクエストを開始する：自然な言葉で Claude に画像を依頼するだけです
2. AI による解釈：Claude がニーズを理解し、最適化されたパラメーターで stock_photo ツールを呼び出します
3. 画像をスマートに選択する：サーバーが文脈を解釈し、最も関連性の高い画像を見つけます
4. 候補を提示する：Claude が最適な候補とダウンロードコマンドを提示します
5. シームレスにダウンロードする：提案されたコマンドを実行すると、必要な場所に画像が保存されます
6. 帰属情報を自動的に記録する：すべての帰属情報が保存され、必要なときにいつでも参照できます

このプロセスにより、従来の次のようなワークフローが不要になります：

1. Unsplash を手動で検索する
2. 何百もの検索結果をスクロールする
3. 画像を適当な場所にダウンロードする
4. ファイルを正しいプロジェクトフォルダーに移動する
5. 帰属情報を手動で管理する
6. 帰属情報のページを作成する

AI エージェント向けプロンプトの例

次のような自然な言葉のプロンプトを使って、Cursor の Claude に画像を依頼できます：

"Find a professional image for a tech startup landing page hero section"

🪟 Windows との互換性

Windows を使用していて、Cursor で MCP サーバーを実行した際に「Client closed」エラーが発生する場合は、次の特別な設定手順に従ってください：

Windows 固有の MCP 設定

.cursor ディレクトリ（通常は %USERPROFILE%\.cursor\mcp.json）に mcp.json という名前のファイルを作成し、次のいずれかの設定を記述します：

オプション 1：Node を直接実行する（推奨）

{
  "mcpServers": {
    "stock_photo": {
      "command": "node",
      "args": ["./node_modules/.bin/tsx", "path/to/unsplash-mcp/src/server.ts"],
      "disabled": false,
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_api_key_here"
      },
      "shell": false
    }
  }
}

オプション 2：PowerShell を使用する

{
  "mcpServers": {
    "stock_photo": {
      "command": "powershell",
      "args": ["-Command", "npx tsx path/to/unsplash-mcp/src/server.ts"],
      "disabled": false,
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_api_key_here"
      }
    }
  }
}

Windows との互換性に関する詳細なドキュメントについては、Windows 互換性ガイドを参照してください。

🛠️ API リファレンス

URL ファーストアプローチ：賢い選択

当社のアーキテクチャでは、いくつかの重要な理由から、画像を直接埋め込むのではなく、URL ファーストのアプローチを採用しています。

1. ストレージ効率：AI エージェントが大きなバイナリデータをコンテキストに不必要に保存するのを防ぎます
2. 帯域幅の節約：サービス間のデータ転送を減らし、応答時間を短縮します
3. 配置の柔軟性：開発者が必要な場所に画像をダウンロードできるようにします
4. 権限管理：制限された環境でのファイルシステム権限の問題を回避します
5. ワークフローとの統合：既存の開発パイプラインにシームレスに統合します

この戦略により、AI エージェントは自身の環境上の制約に縛られることなく、プロジェクトのコンテキストに基づいて最適なダウンロード先をインテリジェントに提案できます。

ツールの過剰な呼び出しと API 呼び出しを最小限に抑える

画像の検索、絞り込み、ダウンロード、帰属表示に複数回のツール呼び出しが必要な他のソリューションとは異なり、当社のサーバーは次の機能を備えています。

• 画像のワークフロー全体を単一の stock_photo ツールに統合
• より適切な絞り込みを可能にするため、あらかじめ多くの画像をリクエストして結果の取得を最適化
• エージェントとサービス間のピンポンのようなやり取りを解消
• リクエストとレスポンスの形式を簡素化し、エージェントのトークン使用量を削減

この設計により、API 呼び出しとツールの実行回数が大幅に減り、結果の取得が速くなり、運用コストも低下します。

🔄 自動帰属表示とコンプライアンス

Unsplash の利用規約：簡単にコンプライアンスを遵守

Unsplash の画像を使用するには、利用規約を遵守する必要があります。当社のサーバーがこの処理を自動化します。

1. 帰属情報の取得：画像をダウンロードするたびに、撮影者の情報が自動的に保存されます
2. メタデータの埋め込み：撮影者の詳細情報が画像ファイルに直接埋め込まれます
3. 帰属情報データベース：ローカルデータベースに、すべての画像の使用記録が保存されます
4. 帰属表示の生成：組み込みツールで HTML および React の帰属表示コンポーネントを作成できます
5. API アクセス：任意のプロジェクトの帰属情報を取得するためのシンプルなエンドポイントを利用できます

当社の Unsplash Smart MCP Server を使用すると、追加の手間をかけずに Unsplash の要件を自動的に遵守できます。

帰属情報管理システム

サーバーには、包括的な帰属情報管理システムが含まれています。

// Retrieve attribution data for your project
const attributions = await fetch('http://localhost:3000/api/unsplash', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    method: 'get_attributions',
    params: {
      format: 'json',  // Options: json, html, react
      projectPath: '/path/to/your/project'
    }
  })
}).then(res => res.json());

// attributions contains complete data about every image used

API では、次の 3 種類の帰属表示ファイルを生成できます。

1. JSON：カスタム実装向けの構造化データ
2. HTML：ウェブサイトのフッターやクレジット欄にすぐに使える HTML ページ
3. React：最新のウェブアプリケーションにすぐ組み込める React コンポーネント

💼 開発者のワークフローへの統合

実際のユースケース

当社の Unsplash Smart MCP Server は、開発者のワークフローにシームレスに統合されます。

UI 開発

• モックアップに関連性の高いプレースホルダー画像をすぐに配置
• コンポーネント間で画像の寸法を一貫して維持
• プロジェクトの構成に沿って画像を論理的に整理

ドキュメント

• 説明用の画像を追加して技術ドキュメントを充実
• 見栄えのよいチュートリアルやガイドを作成
• すべてのビジュアルアセットに適切な帰属表示を維持

コンテンツ作成

• ブログ記事や記事に使う画像をすばやく検索
• ソーシャルメディアコンテンツ用のビジュアルを生成
• 製品マーケティング用に一貫性のある画像を利用

アプリケーション開発

• EC サイトに商品画像を配置
• 視覚的に豊かなユーザー体験を作成
• セクションごとに画像コレクションを分けて管理

フレームワーク別の整理

画像はプロジェクトの種類に応じて自動的に整理されます。

フレームワーク	デフォルトの画像パス	代替パス
Next.js	/public/images/	/public/assets/images/
React	/src/assets/images/	/assets/images/
Vue	/src/assets/images/	/public/images/
Angular	/src/assets/images/	/assets/images/
Generic	/assets/images/	~/Downloads/stock-photos/

🥇 競合との差別化

Unsplash 連携を選ぶ理由

機能	Unsplash Smart MCP サーバー	代替手段
AI エージェント連携	✅ AI エージェントのワークフロー向けに専用設計	❌ 通常、パラメーターを手動で設定する必要があります
コンテキスト認識	✅ 曖昧なリクエストを賢く解釈します	❌ 正確なキーワードの一致に依存します
ツールの効率性	✅ 1 つのツールでワークフロー全体に対応します	❌ 多くの場合、複数のツールを個別に使う必要があります
帰属表示の管理	✅ 複数の形式に対応した包括的なシステム	❌ 手動での追跡、または基本的なテキスト出力
プロジェクトの整理	✅ フレームワークを考慮したフォルダー構成	❌ 汎用的な方法で 1 か所にダウンロードします
インストールの複雑さ	✅ 簡単な 1 行のコマンド	❌ 多くの場合、複数の設定手順が必要です
応答形式	✅ 関連するコンテキストを含む AI 向けに最適化された形式	❌ 追加処理が必要な汎用的な JSON
ダウンロードの柔軟性	✅ URL を優先し、インテリジェントな候補を提示します	❌ 直接ダウンロードのみ、または URL のみ

⚙️ 設定

環境変数

変数	説明	デフォルト
UNSPLASH_ACCESS_KEY	Unsplash API のアクセスキー	-
PORT	サーバーがリッスンするポート	3000
HOST	サーバーのホスト	localhost
ATTRIBUTION_DB_PATH	帰属表示データベースの保存先パス	~/.unsplash-mcp

ツールのパラメーター

stock_photo

パラメーター	型	説明	デフォルト
query	string	検索対象（指定されていない場合は AI が選択します）	-
purpose	string	画像の使用場所（例：ヒーロー、背景）	-
count	number	返す画像の数	1
orientation	string	希望する向き（any、landscape、portrait、square）	any
width	number	ピクセル単位の目標幅	-
height	number	ピクセル単位の目標高さ	-
minWidth	number	検索結果を絞り込むための最小幅	-
minHeight	number	検索結果を絞り込むための最小高さ	-
outputDir	string	写真の保存先ディレクトリ	~/Downloads/stock-photos
projectType	string	フォルダー構成に使用するプロジェクトの種類（next、react、vue、angular）	-
category	string	画像を整理するためのカテゴリ（例：ヒーロー、背景）	-
downloadMode	string	画像をダウンロードするか、URL を返すか	urls_only

get_attributions

パラメーター	型	説明	デフォルト
format	string	出力形式（json、html、react）	json
projectPath	string	特定のプロジェクトパスに帰属表示を絞り込みます	-
outputPath	string	帰属表示ファイルの保存先	-

🔧 トラブルシューティング

よくある問題と解決方法

問題	解決方法
接続が拒否される	サーバーが設定されたポートで実行されていることを確認してください
認証エラー	Unsplash API キーが正しく設定されていることを確認してください
画像が見つからない	より幅広い検索語句を試すか、検索クエリを確認してください
ダウンロード権限の問題	downloadMode: 'urls_only' を使用し、手動のダウンロードコマンドを実行してください
Docker コンテナが早期に終了する	TypeScript ファイルを tsx で直接実行するのではなく、Dockerfile で CMD ["npm", "start"] を使用していることを確認してください。これにより、Docker 環境でサーバーが実行され続けます。
タイムアウトエラー	MCP のデフォルトのタイムアウトは 60 秒です。大きな画像のダウンロードや複数の画像の処理には不十分な場合があります。画像を多く扱う操作では、次の方法をお試しください：1) リクエストごとの画像数を減らす、2) 画像の寸法を小さくする、3) 自動ダウンロードの代わりに urls_only モードを使用する、4) ネットワーク接続を確認する
帰属情報が見つからない	画像が MCP サーバー経由でダウンロードされたことを確認してください
未処理の MCP エラー	"McpError: MCP error -32001: Request timed out" エラーが表示される場合、リクエストの処理に時間がかかりすぎている可能性があります。操作を小さく分割するか、URL のみを使用する方法をお試しください

🤝 コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。

開発ワークフロー

1. リポジトリをクローンします
2. npm install で依存関係をインストールします
3. Unsplash API キーを設定した .env ファイルを作成します
4. npm run dev で開発モードで実行します
5. npm test でテストを実行します

🗺️ ロードマップ

今後のリリースで予定している内容は次のとおりです。

• 画像編集機能：基本的なサイズ変更、トリミング、調整ツール
• 高度な検索フィルター：画像選択をより細かく制御
• バッチ処理：複数の画像リクエストを効率的に処理
• カスタムコレクション：プロジェクト用の画像グループを保存、管理
• チームコラボレーション：帰属情報と画像コレクションを共有
• 使用状況の分析：プロジェクト全体での画像使用状況を追跡
• 追加の画像ソース：ほかのストックフォトプロバイダーとの連携
• タイムアウト処理の改善：タイムアウト設定と復旧メカニズムの強化

📄 ライセンス

MIT License

📚 帰属表示の要件

Unsplash の画像を使用する場合は、Unsplash License に従う必要があります。

• 帰属表示は必須ではありませんが、推奨されています
• 写真の未加工の複製を販売することはできません
• Unsplash の写真を集めて、競合サービスを作成することはできません

当サーバーの帰属表示システムを使えば、写真家に適切なクレジットを簡単に付与できます。

📞 お問い合わせ

問題や質問がある場合は、GitHub でイシューを作成してください。

🧰 開発とテスト

サーバーをローカルで実行する

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

# Install dependencies
npm install

# Set up your environment variables
cp .env.example .env
# Edit .env to add your UNSPLASH_ACCESS_KEY

# Start the development server
npm run dev

テスト

このパッケージには、包括的なテストスイートが含まれています。

# Run core tests
npm test

# Run all tests and get a summary report
npm run test:all

テストスイートには次の項目が含まれています。

• ユニットテストと統合テスト
• ツールの手動テスト
• Docker コンテナのテスト
• Smithery.ai の統合テスト

テストの詳細については、docs/testing.md を参照してください。

---

AI エージェントに、いつでも最適な画像を。
開発者と AI 愛好家のために ❤️ を込めて構築しました。