mcp-server-pexels

Pexelsのストックフォトおよび動画検索用のMCPサーバーです。LLM向けに最適化されています。

Pexelsは、無料のストックフォトと動画を提供しています。

機能

• 写真検索 — フィルター（クエリ、向き、サイズ、色、ロケール）を使用して写真を検索

• 動画検索 — 動画を検索し、1920x1080に最も近いHD .mp4を自動選択

• 詳細取得 — IDを指定して写真/動画の完全なメタデータを取得

• インテリジェントキャッシュ — 検索には10分、ID検索には60分のTTLを設定

• エラーハンドリング — MCPのベストプラクティスに従い、役立つメッセージとともに適切に失敗を処理

• 帰属表示 — すべての結果に必須の撮影者クレジットを表示

前提条件

• Node.js v20以上

• Pexels APIキー（pexels.com/apiで無料取得可能）

クイックスタート（2分）

1. APIキーを取得する

pexels.com/apiでサインアップしてください（無料、クレジットカード不要）。

2. サーバーをビルドする

npm install && npm run build

3. Claude Desktopに追加する

~/Library/Application Support/Claude/claude_desktop_config.json (Mac) または %APPDATA%\Claude\claude_desktop_config.json (Windows) を開き、以下を追加します：

{
  "mcpServers": {
    "pexels": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-pexels/build/index.js"],
      "env": {
        "PEXELS_API_KEY": "YOUR_PEXELS_API_KEY"
      }
    }
  }
}

Windowsの注意点: node.exeのフルパスを使用するか、NodeをPATHに追加してください。Windowsでもパスにはスラッシュを使用できます。

4. Claude Desktopを再起動する

これで、pexels_search_photos、pexels_search_videos、pexels_get_detailsとしてサーバーが利用可能になります。

設定

.mcp.jsonまたはclaude_desktop_config.jsonに追加してください：

{
  "mcpServers": {
    "pexels": {
      "command": "node",
      "args": ["/absolute/path/to/build/index.js"],
      "env": {
        "PEXELS_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

環境変数

環境変数にPEXELS_API_KEYを設定してください。ローカル開発用には.envファイルを作成します：

PEXELS_API_KEY=your_pexels_api_key

開発

npm run dev      # watch mode
npm run inspector # MCP Inspector
npm test          # run tests

ツール

アーキテクチャ

• src/index.ts — エントリーポイント、MCPサーバーのセットアップ

• src/tools/ — ツールの実装

• src/shared/ — キャッシュ、APIクライアント、エラー、型定義、動画セレクター

• src/utils/ — Zodバリデーションスキーマ

技術的決定

互換性

StdioClientTransportを介して@modelcontextprotocol/sdk v1.29+でテスト済みです。統合テストスイートはビルドされたサーバーを起動し、すべてのツール呼び出しをSDKのCallToolResultSchemaおよびContentBlockSchemaに対して検証します。

すべての成功したレスポンスの最後のコンテンツ要素として構造化されたJSONブロックが追加され、型付きデータ（id、kind、creatorName、dimensions、URLs）が含まれます。ダウンストリームのクライアントやエージェントフレームワークは、Markdownテキストを正規表現で解析する代わりに、このブロックを直接解析できます。

今後の改善点

• ツール実行のテレメトリ — キャッシュヒット/ミス、クエリ実行時間、エラー率の構造化ログを追加します。これは本番環境でのAIエージェントのトラブルシューティングをサポートし、可観測性のベストプラクティスを実証します。

• メトリクスエンドポイント — 監視用にカウンター（提供されたリクエスト数、キャッシュヒット率、残りのAPIクォータ）を公開します。

• カスタムTTL設定 — 環境変数を通じてユーザーがキャッシュTTLを調整できるようにします。

コミュニティへの貢献

• 大歓迎です！ 🌟

ライセンス

非公式のコミュニティプロジェクトです。Pexelsとは提携していません。