Skip to main content
Glama
deenesjakoruzh
afshinator

mcp-server-pexels

by afshinator
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

mcp-server-pexels

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

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

機能

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

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

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

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

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

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

Related MCP server: Pexels MCP Server

前提条件

  • 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

ツール

ツール

説明

pexels_search_photos

クエリで写真を検索

pexels_search_videos

動画を検索

pexels_get_details

IDとタイプで詳細を取得

アーキテクチャ

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

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

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

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

技術的決定

決定

根拠

キャッシュファーストアーキテクチャ

Pexels APIは1時間あたり200リクエストまでです。キャッシュ（検索は10分TTL、ID検索は60分TTL）によりクォータを節約し、キャッシュヒット時のレイテンシを5ms未満に短縮します。これは、エージェントが頻繁に同じコンテキストを再要求する本番AIシステムにおいて、APIコストを意識する上で重要です。

呼び出し時のフェイルファスト

MCPサーバーは子プロセスとして起動されるため、起動時に失敗させるべきではありません。サーバーは起動時に警告を出しますが、最初のツール呼び出し時に構造化されたisError: trueで適切に失敗を処理します。

Zodバリデーションスキーマ

MCP v2 SDKはz.object()ラッパーを必要とします。APIに到達する前に無効な入力をキャッチします。

メディア用のresource_link

リモート画像と動画は、適切なmimeTypeを持つMCP resource_linkコンテンツブロックとして提供されます。テキストブロック内のMarkdown画像リンクは、resource_linkをレンダリングしないクライアントのためのフォールバックとして残されています。

純粋な動画選択

動画選択ロジックはvideo-selector.tsに分離されており、ツールハンドラーから独立してテスト可能です。

ハードコードされた帰属表示

Pexelsの利用規約で義務付けられています。すべてのテキストレスポンスに埋め込まれています。

互換性

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

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

今後の改善点

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

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

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

コミュニティへの貢献

  • 大歓迎です！ 🌟

ライセンス

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

Available Tools

3 tools
pexels_get_detailsGet Pexels DetailsA
Read-onlyIdempotent

Get detailed information about a specific photo or video by ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYes
typeYes
force_refreshNo

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, non-destructive, and idempotent behavior. The description adds that it returns 'detailed information' but does not disclose any additional behavioral traits like rate limits or required permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with three parameters and no output schema, the description is minimally adequate. It fails to hint at the output format or behavior of the optional 'force_refresh' parameter, leaving some gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description should compensate. It only mentions 'by ID', leaving parameters like 'type' and 'force_refresh' unexplained. While the enum for type provides some guidance, the description adds minimal value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb 'Get', resource 'detailed information about a specific photo or video', and method 'by ID'. It effectively distinguishes from sibling search tools (pexels_search_photos, pexels_search_videos) which query by keywords.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when a specific ID is known, contrasting with search tools. However, it does not explicitly state when not to use it or mention alternative tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pexels_search_photosSearch Pexels PhotosA
Read-onlyIdempotent

Search for stock photos by query with optional filters for orientation, size, color, and locale. Returns 3-5 results with mandatory photographer attribution.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
orientationNo
sizeNo
colorNo
localeNo
per_pageNo
force_refreshNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
idYes
kindYes
creatorNameYes
creatorUrlYes
pageUrlYes
previewUrlYes
mediaUrlYes
mediaMimeTypeYes
dimensionsYes
avgColorYes
altYes

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, non-destructive, and idempotent behavior. The description adds valuable behavioral details: returns 3-5 results and requires photographer attribution, which goes beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, extremely concise, with no filler. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema and annotations, the description covers core functionality well. It lacks mention of per_page and force_refresh, but is otherwise sufficient for a search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description mentions four optional filters (orientation, size, color, locale), adding semantic context that they are filters. However, it omits per_page and force_refresh, and schema coverage is 0%. The added value is marginal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Search for stock photos by query with optional filters', specifying verb and resource. It distinguishes from siblings (pexels_get_details for individual photos, pexels_search_videos for videos) by focusing on photo search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

While the purpose is clear, the description does not provide explicit guidance on when to use this tool versus its siblings or alternatives. Usage is implied but not contrasted.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pexels_search_videosSearch Pexels VideosA
Read-onlyIdempotent

Search for stock videos by query with optional filters. Returns HD-quality .mp4 links with mandatory attribution.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
orientationNo
sizeNo
localeNo
per_pageNo
force_refreshNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
idYes
kindYes
creatorNameYes
creatorUrlYes
pageUrlYes
previewUrlYes
mediaUrlYes
mediaMimeTypeYes
dimensionsYes
durationSecondsYes

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already signal read-only, non-destructive, idempotent behavior. The description adds value by disclosing that results are HD-quality .mp4 links with mandatory attribution, which are not implied by annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the action and key details. Every word earns its place with no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The output schema exists, covering return values. The description adds helpful context on output format and attribution. Missing aspects like pagination and enum specifics are minor given overall clarity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description provides no individual parameter explanations. It only mentions 'optional filters' generically, failing to compensate for the missing schema descriptions of the 6 parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches for stock videos by query with optional filters. It mentions HD-quality .mp4 links and mandatory attribution, which distinguishes it from sibling tools like pexels_search_photos (photos) and pexels_get_details (details).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for video searches via 'stock videos' and optional filters, but does not explicitly state when to use this tool over siblings. However, the tool name and context signals make the distinction clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updates
    • Changedpexels_search_photos1 field changed
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "alt": {
+      "type": "string"
+    },
+    "avgColor": {
+      "type": "string"
+    },
+    "creatorName": {
+      "type": "string"
+    },
+    "creatorUrl": {
+      "type": "string"
+    },
+    "dimensions": {
+      "additionalProperties": false,
+      "properties": {
+        "height": {
+          "type": "number"
+        },
+        "width": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "width",
+        "height"
+      ],
+      "type": "object"
+    },
+    "id": {
+      "type": "number"
+    },
+    "kind": {
+      "const": "photo",
+      "type": "string"
+    },
+    "mediaMimeType": {
+      "const": "image/jpeg",
+      "type": "string"
+    },
+    "mediaUrl": {
+      "type": "string"
+    },
+    "pageUrl": {
+      "type": "string"
+    },
+    "previewUrl": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "id",
+    "kind",
+    "creatorName",
+    "creatorUrl",
+    "pageUrl",
+    "previewUrl",
+    "mediaUrl",
+    "mediaMimeType",
+    "dimensions",
+    "avgColor",
+    "alt"
+  ],
+  "type": "object"
+}
    • Changedpexels_search_videos1 field changed
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "creatorName": {
+      "type": "string"
+    },
+    "creatorUrl": {
+      "type": "string"
+    },
+    "dimensions": {
+      "additionalProperties": false,
+      "properties": {
+        "height": {
+          "type": "number"
+        },
+        "width": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "width",
+        "height"
+      ],
+      "type": "object"
+    },
+    "durationSeconds": {
+      "type": "number"
+    },
+    "id": {
+      "type": "number"
+    },
+    "kind": {
+      "const": "video",
+      "type": "string"
+    },
+    "mediaMimeType": {
+      "type": "string"
+    },
+    "mediaUrl": {
+      "type": "string"
+    },
+    "pageUrl": {
+      "type": "string"
+    },
+    "previewUrl": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "id",
+    "kind",
+    "creatorName",
+    "creatorUrl",
+    "pageUrl",
+    "previewUrl",
+    "mediaUrl",
+    "mediaMimeType",
+    "dimensions",
+    "durationSeconds"
+  ],
+  "type": "object"
+}
  2. 3 tool updatesv1.0.0
    • First observedpexels_get_details
    • First observedpexels_search_photos
    • First observedpexels_search_videos
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: searching photos, searching videos, and getting details by ID. No overlap or ambiguity.

Naming Consistency5/5

All tools follow a consistent 'pexels_verb_noun' pattern using snake_case, making it predictable for an agent to infer functionality.

Tool Count4/5

Three tools is minimal but appropriate for a focused image/video search service. It covers the core workflow without unnecessary bloat.

Completeness4/5

The set covers search and retrieval of photos and videos, but lacks features like curated collections or trending content, which are minor omissions.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers