mcp-server-pexels

Ein MCP-Server für die Suche nach Stockfotos und -videos von Pexels. Optimiert für LLMs.

Pexels bietet kostenlose Stockfotos und -videos.

Funktionen

• Fotosuche — Suche nach Fotos mit Filtern (Suchbegriff, Ausrichtung, Größe, Farbe, Gebietsschema)

• Videosuche — Suche nach Videos, wählt automatisch das HD-.mp4-Video aus, das 1920x1080 am nächsten kommt

• Details abrufen — Vollständige Metadaten für ein Foto/Video per ID abrufen

• Intelligentes Caching — 10 Min. TTL für Suchen, 60 Min. für ID-Abfragen

• Fehlerbehandlung — Sanfte Fehlerbehandlung mit hilfreichen Meldungen (gemäß MCP-Best-Practices)

• Namensnennung — Obligatorische Fotografen-Credits in jedem Ergebnis

Voraussetzungen

• Node.js v20+

• Pexels API-Schlüssel (kostenlos unter pexels.com/api)

Schnellstart (2 Minuten)

1. API-Schlüssel erhalten

Registrieren Sie sich unter pexels.com/api — kostenlos, keine Kreditkarte erforderlich.

2. Server erstellen

npm install && npm run build

3. Zu Claude Desktop hinzufügen

Öffnen Sie ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) oder %APPDATA%\Claude\claude_desktop_config.json (Windows) und fügen Sie Folgendes hinzu:

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

Windows-Hinweis: Verwenden Sie den vollständigen Pfad zu node.exe oder fügen Sie Node zum PATH hinzu. Schrägstriche in Pfaden funktionieren unter Windows.

4. Claude Desktop neu starten

Der Server ist nun als pexels_search_photos, pexels_search_videos und pexels_get_details verfügbar.

Konfiguration

Fügen Sie dies zu Ihrer .mcp.json oder claude_desktop_config.json hinzu:

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

Umgebung

Setzen Sie PEXELS_API_KEY in Ihrer Umgebung. Erstellen Sie für die lokale Entwicklung eine .env-Datei:

PEXELS_API_KEY=your_pexels_api_key

Entwicklung

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

Tools

Architektur

• src/index.ts — Einstiegspunkt, MCP-Server-Setup

• src/tools/ — Tool-Implementierungen

• src/shared/ — Cache, API-Client, Fehler, Typen, Video-Selektor

• src/utils/ — Zod-Validierungsschemata

Technische Entscheidungen

Kompatibilität

Getestet mit @modelcontextprotocol/sdk v1.29+ via StdioClientTransport. Die Integrationstest-Suite startet den erstellten Server und validiert jeden Tool-Aufruf gegen das CallToolResultSchema und ContentBlockSchema des SDKs.

Ein strukturierter JSON-Block wird als letztes Inhaltselement an jede erfolgreiche Antwort angehängt und enthält typisierte Daten (ID, Art, Erstellername, Abmessungen, URLs). Nachgelagerte Clients und Agenten-Frameworks können diesen Block direkt parsen, anstatt den Markdown-Text per Regex zu analysieren.

Zukünftige Verbesserungen

• Tool-Ausführungs-Telemetrie — Hinzufügen von strukturiertem Logging für Cache-Treffer/-Fehlschläge, Abfrageausführungszeit und Fehlerraten. Dies unterstützt die Fehlerbehebung bei KI-Agenten in der Produktion und demonstriert Best Practices für die Beobachtbarkeit.

• Metriken-Endpunkt — Bereitstellung von Zählern (bediente Anfragen, Cache-Trefferquote, verbleibendes API-Kontingent) für das Monitoring.

• Benutzerdefinierte TTL-Konfiguration — Ermöglicht Benutzern die Anpassung der Cache-TTL über Umgebungsvariablen.

Community-Beiträge

• sind willkommen! 🌟

Lizenz

Inoffizielles Community-Projekt. Nicht mit Pexels verbunden.