MCP Pexels

mcp-pexels — Claude、Cursor、その他の AI エージェント向け Pexels MCP サーバー

Model Context Protocol サーバーです。Pexels API が提供する無料のストック写真、動画、厳選コレクションを MCP ツールとして公開し、互換性のある AI クライアント（Claude Desktop、Claude Code、Cursor、Cline、Continue など）からチャット内で直接呼び出せます。

📦 npm： mcp-pexels · 🏷 最新リリース： v1.0.0 · 💻 ソース： developer-ishan/mcp-pexels

写真と動画は Pexels 提供です。

すぐに使える設定

{
  "mcpServers": {
    "pexels": {
      "command": "npx",
      "args": ["-y", "mcp-pexels"],
      "env": { "PEXELS_API_KEY": "your_key_here" }
    }
  }
}

MCP クライアントの設定に貼り付けて再起動すると、9 つの pexels_* ツールが利用可能になります。無料のキーは https://www.pexels.com/api/ から取得できます。

---

目次

• このツールで何ができますか？
• 機能 — 9 つのツール
• MCP クライアントへの接続
  • Claude Desktop
  • Claude Code
  • Cursor
  • Cline (VS Code)
  • Continue.dev
  • 汎用／その他のクライアント
• プロンプトの例
• 比較
• よくある質問
• 要件
• 開発
• リリース
• コントリビューション
• クレジット表記とライセンス

---

このツールで何ができますか？

mcp-pexels を AI クライアントに接続すると、エージェントはロイヤリティフリーの写真や動画をワークフローに直接取り込めます。具体的な活用例をいくつか紹介します。

• スライド資料やドキュメントへの画像追加 — 「スライド 3 用に、夕焼けの山の風景写真を探して」→ エージェントが Pexels を検索し、写真を選んで埋め込みます。
• ブログ記事／ソーシャルメディアの下書き — 「リモートワークに関する記事のサムネイル候補を 3 つ提案して」→ 写真家のクレジット付きで、Pexels の URL を 3 つ返します。
• 動画編集のための背景調査 — 「4K で 30 秒未満の人気のドローン映像を見せて」→ サイズと再生時間のフィルターを指定して pexels_popular_videos を使用します。
• ムードボード — 「暖色系のコーヒーショップの写真でムードボードを作って」→ color: "orange" を指定して検索します。
• コーディングエージェント — lorem-pixel のプレースホルダーの代わりに、リアルな仮画像を使った CSS／HTML を生成します。
• 厳選コレクション — 特定の Pexels コレクション（例：Pexels 上でタグ付けされた企業所有の写真）をエージェントのコンテキストに取り込みます。

すべてのレスポンスに _rateLimit オブジェクトが含まれるため、エージェントは自らリクエスト頻度を調整し、Pexels の無料プランの上限（1 時間あたり 200 リクエスト、月あたり 20,000 リクエスト）を守ることができます。

---

機能 — 9 個のツール

分野	ツール	説明
写真	pexels_search_photos	向き／サイズ／色／ロケールのフィルターを指定して、クエリで写真を検索します。
写真	pexels_curated_photos	Pexels チームがリアルタイムで選定した写真フィードを取得します。
写真	pexels_get_photo	数値 ID を指定して、1 枚の写真を取得します。
動画	pexels_search_videos	向き／サイズ／ロケールのフィルターを指定して、クエリで動画を検索します。
動画	pexels_popular_videos	幅／高さ／長さの条件を任意で指定して、人気の動画を取得します。
動画	pexels_get_video	数値 ID を指定して、1 本の動画を取得します。
コレクション	pexels_featured_collections	Pexels の注目コレクションを一覧表示します。
コレクション	pexels_my_collections	認証済みユーザー自身のコレクションを一覧表示します。
コレクション	pexels_collection_media	指定したコレクション内の写真と動画を取得します。

各ツールの応答は、トップレベルの _rateLimit フィールド（limit、remaining、reset（UNIX タイムスタンプ）を公開）をマージした、Pexels の生の JSON です。

ツールごとのパラメータ表とペイロードの例については、docs/tools/ を参照してください。

---

MCP クライアントへの接続

以下のすべての手順では npx -y mcp-pexels を使用します。グローバルインストールは不要です。your_key_here を実際の Pexels API キーに置き換えてください。

Claude Desktop

オプション 1 — ワンクリックの .mcpb インストール（推奨）。 リリースページから最新の mcp-pexels-*.mcpb をダウンロードし、ファイルをダブルクリックします。Claude Desktop から求められたら Pexels API キーを貼り付けて、Install をクリックしてください。

オプション 2 — JSON 設定を手動で編集。 claude_desktop_config.json を編集します。

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

{
  "mcpServers": {
    "pexels": {
      "command": "npx",
      "args": ["-y", "mcp-pexels"],
      "env": { "PEXELS_API_KEY": "your_key_here" }
    }
  }
}

Claude Desktop を再起動してください。

Claude Code

claude mcp add pexels -e PEXELS_API_KEY=your_key_here -- npx -y mcp-pexels

または、~/.claude.json を直接編集し、上記と同じ mcpServers ブロックを追加してください。

Cursor

~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクトごと）を編集します。

{
  "mcpServers": {
    "pexels": {
      "command": "npx",
      "args": ["-y", "mcp-pexels"],
      "env": { "PEXELS_API_KEY": "your_key_here" }
    }
  }
}

Cline（VS Code）

Cline 拡張機能の設定を開き、MCP Servers → Edit Settings を選択します。次を追加してください。

{
  "mcpServers": {
    "pexels": {
      "command": "npx",
      "args": ["-y", "mcp-pexels"],
      "env": { "PEXELS_API_KEY": "your_key_here" }
    }
  }
}

Continue.dev

~/.continue/config.json に記述します。

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "mcp-pexels"],
          "env": { "PEXELS_API_KEY": "your_key_here" }
        }
      }
    ]
  }
}

汎用／その他のクライアント

クライアントが stdio MCP サーバーに対応している場合は、command、args、env があれば接続できます。上記の Cursor／Claude Desktop と同じ形式を使用してください。インスペクター／デバッグの場合：

export PEXELS_API_KEY=your_key_here
npx -y @modelcontextprotocol/inspector npx -y mcp-pexels

ブラウザー UI が開き、各ツールを対話形式で呼び出せます。

---

プロンプトの例

接続したら、次のようなプロンプトを試してみてください。

• 「ゴールデンアワーの山の風景写真を 5 枚探してください。少なくともフル HD のものにしてください。」
• 「街の交通を映した、長さ 15 秒未満で 1080p 以上の人気の Pexels 動画を取得してください。」
• 「写真 ID 2014422 を取得して、写真家を教えてください。」
• 「Pexels の注目コレクションを一覧表示してください。料理写真を探せるコレクションが欲しいです。」
• 「縦向きの『forest』の動画を検索して、最も高画質な HD ファイルを選んでください。」
• 「秋をテーマにしたニュースレターのヘッダーに使える、オレンジ系の色調が中心の Pexels 写真を見せてください。」

エージェントが適切なツールを選び、適切なパラメータを送信して、回答に写真家／ビデオグラファーのクレジットを含めます。

---

比較

	mcp-pexels	Pexels REST APIを直接使用	画像専用の汎用 MCP サーバー
写真	✅	✅	さまざま
動画	✅	✅	通常は ❌
コレクション	✅	✅	❌
エージェントにレート制限ヘッダーを公開	✅	❌（生のヘッダーを返すため、エージェントが解析する必要があります）	❌
Zod による入力検証	✅	❌	さまざま
npx でインストール可能、設定不要	✅	❌	さまざま
型安全な TS ソース	✅	該当なし	さまざま
MIT ライセンス	✅	該当なし	さまざま

写真だけが必要で、すでに汎用の画像 MCP サーバーを接続している場合は、それで十分かもしれません。動画とコレクションの本格的なサポートに加え、レート制限にも対応したものが必要な場合は、この用途に特化したものです。

---

FAQ

Pexels API キーを取得するにはどうすればよいですか？

https://www.pexels.com/api/ で登録してください。キーはすぐに発行され、無料プランでは1時間あたり200リクエスト、1か月あたり20 000リクエストが利用できます。

費用はかかりますか？

いいえ。Pexels API は無料で、npm パッケージも無料（MIT）です。また、mcp-pexels 自体が有料サービスを呼び出すことはありません。

オフラインで動作しますか？

いいえ。このサーバーは Pexels HTTPS API の薄いラッパーであり、ネットワーク接続が必要です。

Pexels のコンテンツを商用利用できますか？

はい。Pexels のライセンスに従って利用できますが、プラットフォームと（可能であれば）写真家を明記する必要があります。帰属表示をご覧ください。

Claude.ai（ブラウザー）で動作しますか？

Claude.ai のウェブ製品は、現時点では stdio MCP サーバーをサポートしていません。対応しているのは Claude Desktop、Claude Code、API のみです。Anthropic はブラウザーでの MCP サポートを順次提供しているため、今後変更されるはずです。

ホスト型／SaaS 版はありますか？

いいえ。npx を使ってローカルで実行してください。Pexels API キーはユーザーごとに発行されるため、共有インスタンスをホストしても意味がありません。

新しいバージョンに更新するにはどうすればよいですか？

npx は常に公開済みの最新バージョンを取得します。グローバルにインストールした場合は、npm update -g mcp-pexels を実行してください。

Pexels のエンドポイントを追加できますか？

Pexels API のエンドポイントはすべて実装済みです（Pexels API v1 の9/9エンドポイント）。新しいエンドポイントは PR で追加できます。コントリビューションをご覧ください。

@modelcontextprotocol/inspector で動作しますか？

はい：

export PEXELS_API_KEY=your_key_here
npx -y @modelcontextprotocol/inspector npx -y mcp-pexels

レート制限にはどのように対応していますか？

各ツールの応答には、limit、remaining、reset（UNIX タイムスタンプ）を含む _rateLimit オブジェクトが含まれます。エージェントはこれを読み取り、自身でリクエスト頻度を調整できます。Pexels が 429 を返した場合、サーバーは PexelsApiError として通知するため、エージェントは失敗を認識できます。

API キーはどこで使われますか？

ローカルプロセスの PEXELS_API_KEY 環境変数から読み取られます。api.pexels.com への Authorization ヘッダーに含めて送信する場合を除き、マシンの外に出ることはありません。ログにも記録されません。

---

要件

• Node.js ≥ 20（ネイティブの fetch と --env-file を使用）
• 無料の Pexels API キー — こちらからリクエストしてください

---

開発

git clone https://github.com/developer-ishan/mcp-pexels.git
cd mcp-pexels
npm install
echo "PEXELS_API_KEY=your_key_here" > .env

npm test           # 42 mocked vitest cases, no network
npm run build      # tsc → dist/
npm run dev        # tsx watch
npm run test:watch # vitest in watch mode
npm start          # node --env-file=.env dist/index.js

プロジェクト構成

src/
├── index.ts                  # MCP server entrypoint (stdio)
├── http/
│   ├── client.ts             # PexelsClient (injectable fetch for tests)
│   └── types.ts              # PexelsApiError, RateLimit, PexelsResponse
├── tools/
│   ├── index.ts              # composes the three domain factories
│   ├── photos.ts             # 3 photo tools
│   ├── videos.ts             # 3 video tools
│   └── collections.ts        # 3 collection tools
└── types/
    ├── tool.ts               # defineTool helper + ToolDefinition
    ├── photos.ts
    ├── videos.ts
    └── collections.ts

tests/
├── helpers/mockClient.ts     # makeMockClient() — fake fetch via vitest mocks
├── photos.test.ts            # 17 cases
├── videos.test.ts            # 13 cases
└── collections.test.ts       # 12 cases

テスト方針

テストでは、makeMockClient(responses) が返す vi.fn() の fetchImpl を使って PexelsClient を構築します。実際の HTTP 通信は行いません。各ツールについて、次の項目をテストします。

1. 正常系 — URL のシリアライズと Authorization ヘッダー。
2. エラーマッピング — 2xx 以外の応答が、status と body を含む PexelsApiError になること。
3. Zod による検証 — 必須パラメーター、列挙型の値、整数の範囲。

---

リリース

このリポジトリでは、タグをトリガーとするリリースワークフロー（.github/workflows/release.yml）を使用しています。

1. バージョンを更新します：npm version patch（または minor／major）。コミットとタグが作成されます。
2. プッシュします：git push && git push --tags。
3. ワークフローがテストを実行し、ビルドを行い、リポジトリシークレットの NPM_TOKEN を使って来歴情報付きで npm に公開します。さらに、npm run pack:mcpb で**.mcpb バンドル**をビルドし、自動生成のリリースノートを含む GitHub リリースを作成して、バンドルをダウンロード可能なアセットとして追加します。

バージョン履歴については、CHANGELOG.md をご覧ください。

---

貢献

Issue やプルリクエストを歓迎します。開発ワークフローについては CONTRIBUTING.md を、脆弱性を非公開で報告する方法については SECURITY.md をご覧ください。

mcp-pexels をツールや製品に組み込んで公開する場合は、CONTRIBUTING.md の「使用例」リストに追加するプルリクエストを作成してください。

掲載先／申請先

• Smithery — smithery.yaml により自動検出されます。
• mcp.so — コミュニティディレクトリです。
• awesome-mcp-servers — 厳選された GitHub リストです。
• modelcontextprotocol/servers — Anthropic の公式ディレクトリです。

申請方法の早見表は docs/MARKETPLACES.md をご覧ください。

---

クレジットとライセンス

Pexels のコンテンツを使用する場合は、Pexels API のガイドラインに従ってください。

• Pexels へのリンクを目立つように表示してください。例："Pexels 提供の写真"。
• 可能であれば、写真家やビデオグラファーのクレジットを記載してください。例："Pexels の John Doe による写真"。

mcp-pexels パッケージ自体は、MIT License のもとで公開されています。