image-resolver

MCP Image Resolver Server

Cursor、Claude Desktop、VS Code、Windsurf などの AI ホスト向けに、ロイヤリティフリー画像検索を提供する MCP（Model Context Protocol）サーバーです。AI アシスタントに自然言語で画像を探すよう依頼すると、search_images ツールを使って Pexels と Unsplash から構造化された検索結果を返します。

機能

• search_images — ロイヤリティフリー画像を検索します（件数、ページ、向きを指定できます）
• extract_image_query — 自由形式のテキストを画像検索クエリに変換します
• get_best_image — クエリに最適な画像を1枚返します
• search_images_batch — 複数の検索を並列で実行します
• resolve_image_attribution — プロバイダーの要件に準拠したクレジット表記を生成します
• Pexels & Unsplash — 複数プロバイダーに対応（どちらも無料プランを利用可能）
• 統一されたレスポンス — URL、ソース、寸法、撮影者、タグを含む構造化された検索結果
• あらゆる環境で動作 — stdio サーバーに対応するすべての MCP クライアントで利用可能です

要件

• Node.js 18+
• 少なくとも1つの API キー：Pexels（pexels.com/api）および／または Unsplash（unsplash.com/oauth/applications）

クイックスタート（インストール不要）

クローンやビルドは不要です。MCP クライアントにこの設定を追加するだけで、npx 経由で自動的に実行されます。

{
  "mcpServers": {
    "image-resolver": {
      "command": "npx",
      "args": ["-y", "@ahmaddioxide/mcp-image-resolver"],
      "env": {
        "PEXELS_API_KEY": "your-pexels-api-key",
        "UNSPLASH_ACCESS_KEY": "your-unsplash-access-key"
      }
    }
  }
}

少なくとも1つの API キーが必要です。どちらも無料です。こちらから取得してください。

• Pexels：pexels.com/api
• Unsplash：unsplash.com/oauth/applications

アーキテクチャ（概要）

┌─────────────────────────────────────────────────────────────────────────────┐
│                           MCP Client (Cursor, Claude, VS Code, etc.)        │
│                                     │                                       │
│                            stdio (stdin/stdout)                             │
└─────────────────────────────────────┼───────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         MCP Image Resolver Server                           │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  index.ts          MCP server entry, registers tools, stdio transport│   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                      │                                      │
│                                      ▼                                      │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  tools/search-images.ts   Tool handler: search_images(query)         │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                      │                                      │
│                                      ▼                                      │
│  ┌──────────────────────┐  ┌──────────────────────┐                        │
│  │  providers/pexels.ts  │  │ providers/unsplash.ts │                        │
│  │  Pexels API adapter   │  │ Unsplash API adapter  │──▶ ImageResult schema  │
│  └──────────────────────┘  └──────────────────────┘                        │
│               │                        │                                    │
│               └────────────────────────┴────▶ utils/normalize.ts            │
└─────────────────────────────────────┼───────────────────────────────────────┘
                                      │
                    ┌─────────────────┴─────────────────┐
                    ▼                                   ▼
┌──────────────────────────────┐    ┌──────────────────────────────────────────┐
│  Pexels API                  │    │  Unsplash API                             │
│  api.pexels.com              │    │  api.unsplash.com                         │
└──────────────────────────────┘    └──────────────────────────────────────────┘

フロー： MCP クライアント → stdio → index.ts（ツールを登録）→ search-images.ts → Pexels と Unsplash のプロバイダー（キーが設定されている場合）。検索結果は統合され（Pexels が先、次に Unsplash）、統一された ImageResult スキーマに正規化されます。

クライアントの設定

Cursor

.cursor/mcp.json（プロジェクト）または ~/.cursor/mcp.json（グローバル）に追加します。

{
  "mcpServers": {
    "image-resolver": {
      "command": "npx",
      "args": ["-y", "@ahmaddioxide/mcp-image-resolver"],
      "env": {
        "PEXELS_API_KEY": "your-pexels-api-key",
        "UNSPLASH_ACCESS_KEY": "your-unsplash-access-key"
      }
    }
  }
}

設定を変更した後は Cursor を再起動してください。

Claude Desktop

Claude の設定ファイルに追加します。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

設定から：Developer → Edit Config

{
  "mcpServers": {
    "image-resolver": {
      "command": "npx",
      "args": ["-y", "@ahmaddioxide/mcp-image-resolver"],
      "env": {
        "PEXELS_API_KEY": "your-pexels-api-key",
        "UNSPLASH_ACCESS_KEY": "your-unsplash-access-key"
      }
    }
  }
}

保存した後は Claude Desktop を完全に終了してから再起動してください。

VS Code

.vscode/mcp.json（ワークスペース）またはユーザープロファイルの mcp.json に追加します。

{
  "servers": {
    "image-resolver": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ahmaddioxide/mcp-image-resolver"],
      "env": {
        "PEXELS_API_KEY": "your-pexels-api-key",
        "UNSPLASH_ACCESS_KEY": "your-unsplash-access-key"
      }
    }
  }
}

注： VS Code では mcpServers ではなく servers を使用し、"type": "stdio" が必要です。

Windsurf

~/.codeium/windsurf/mcp_config.json に追加します。

{
  "mcpServers": {
    "image-resolver": {
      "command": "npx",
      "args": ["-y", "@ahmaddioxide/mcp-image-resolver"],
      "env": {
        "PEXELS_API_KEY": "your-pexels-api-key",
        "UNSPLASH_ACCESS_KEY": "your-unsplash-access-key"
      }
    }
  }
}

変更後は MCP 設定を更新してください。

その他の MCP クライアント

stdio MCP サーバーに対応するクライアント（Amp、Continue.dev、Amazon Q など）であれば、どれでもこのサーバーを使用できます。

• コマンド：npx
• 引数：["-y", "@ahmaddioxide/mcp-image-resolver"]
• 環境変数：{ "PEXELS_API_KEY": "your-key", "UNSPLASH_ACCESS_KEY": "your-key" }（少なくとも1つ必要）

使い方

設定が完了したら、AI アシスタントに自然言語で画像を探すよう依頼してください。search_images ツールが自動的に呼び出されます。

プロンプトの例：

• 「夕焼けのモスクのロイヤリティフリー画像を探してください」
• 「ウェルネスアプリに合う禅やヨガの画像を検索してください」
• 「ミニマルなオフィスのワークスペースの写真をいくつか見つけてください」
• 「料理ブログのヘッダー用画像を探してください」

このツールは画像の URL とメタデータを返します。リンクを使って画像を表示またはダウンロードしてください。

ツールスキーマ

ツール	パラメーター	説明
search_images	query, limit?, page?, orientation?	Pexels と Unsplash から画像を検索します
extract_image_query	context	自由形式のテキストから検索語を抽出します
get_best_image	query, orientation?	最適な画像を 1 枚返します
search_images_batch	queries, limit?	複数の検索を並行して実行します
resolve_image_attribution	photographer, source, url?	クレジット表記を生成します

レスポンス： results 配列を含む JSON で、各要素は { url, source, width, height, photographer, tags } です。各結果には、クレジット表記用の source（"Pexels" または "Unsplash"）が含まれます。

注： 両方のプロバイダーが設定されている場合、結果は Pexels、Unsplash の順に統合されます。1 回の検索で両方のプロバイダーの結果を表示するには、limit: 20 以上を指定してください。

テスト

ツールの動作を確認するためのプロンプト例：

• 「山の風景を検索し、limit 20 を指定して、どの結果が Pexels と Unsplash のものか教えてください。」
• 「次の内容に対して extract_image_query を使用してください：山のある瞑想アプリのヒーロー画像が必要です。」
• 「「sunset mosque」、「pakistani flag」、「zen yoga」に対して search_images_batch を使用してください。」
• 「コーヒーショップに最適な画像を 1 枚取得し、その画像のクレジット表記を生成してください。」

開発

コントリビュートする場合やローカルで実行する場合は、リポジトリをクローンしてソースからビルドしてください。

git clone https://github.com/ahmaddioxide/image-resolver-mcp.git
cd image-resolver-mcp
npm install
cp .env.example .env
# Add PEXELS_API_KEY and/or UNSPLASH_ACCESS_KEY to .env
npm run build

または、tsx を使ってビルドせずに開発モードで実行できます。

{
  "mcpServers": {
    "image-resolver": {
      "command": "npx",
      "args": ["tsx", "/path/to/image-resolver-mcp/src/index.ts"],
      "env": {
        "PEXELS_API_KEY": "your-pexels-api-key",
        "UNSPLASH_ACCESS_KEY": "your-unsplash-access-key"
      }
    }
  }
}

クレジット表記

画像は Pexels と Unsplash から取得しています。各 API の利用規約に従い、以下を守ってください。

• Pexels と Unsplash へのリンクを目立つように掲載する
• 写真家のクレジットを表記する：「Photo by [Name] on Pexels」／「Photo by [Name] on Unsplash」
• レスポンスのメタデータには photographer と source が含まれます。規約に準拠したテキストを使用するには、resolve_image_attribution を使ってください

コントリビュート

コントリビュートを歓迎します。ガイドラインについては CONTRIBUTING.md、コミュニティの行動規範については CODE_OF_CONDUCT.md をお読みください。脆弱性の報告については SECURITY.md をご覧ください。

ライセンス

MIT — LICENSE をご覧ください。