actors-mcp-server

Apify Model Context Protocol (MCP)-Server

Implementierung eines MCP-Servers für alle Apify-Akteure . Dieser Server ermöglicht die Interaktion mit einem oder mehreren Apify-Akteuren, die in der MCP-Serverkonfiguration definiert werden können.

Der Server kann auf zwei Arten verwendet werden:

• 🇦 MCP Server Actor – HTTP-Server, auf den über Server-Sent Events (SSE) zugegriffen werden kann, siehe Anleitung
• ⾕ MCP Server Stdio – Lokaler Server verfügbar über Standard-Eingabe/Ausgabe (stdio), siehe Anleitung

Sie können auch mit dem MCP-Server über eine chatähnliche Benutzeroberfläche mit 💬 Tester MCP Client interagieren.

🎯 Was macht der Apify MCP-Server?

Der MCP-Server-Akteur ermöglicht es einem KI-Assistenten, jeden Apify-Akteur als Werkzeug zur Ausführung einer bestimmten Aufgabe zu verwenden. Beispielsweise kann er:

• Verwenden Sie Facebook Posts Scraper , um Daten aus Facebook-Posts von mehreren Seiten/Profilen zu extrahieren
• Verwenden Sie den Google Maps Email Extractor , um die Kontaktdaten von Google Maps zu extrahieren
• Verwenden Sie den Google Search Results Scraper, um die Suchergebnisseiten (SERPs) von Google zu scrapen
• Verwenden Sie Instagram Scraper , um Instagram-Beiträge, Profile, Orte, Fotos und Kommentare zu scrapen
• Verwenden Sie den RAG-Webbrowser, um das Web zu durchsuchen, die Top-N-URLs zu scrapen und deren Inhalt zurückzugeben

MCP-Kunden

Zur Interaktion mit dem Apify MCP-Server können Sie MCP-Clients verwenden wie:

• Claude Desktop (nur Stdio-Unterstützung)
• Visual Studio Code (Standard- und SSE-Unterstützung)
• LibreChat (Standard- und SSE-Unterstützung, jedoch ohne Autorisierungsheader)
• Apify Tester MCP-Client (SSE-Unterstützung mit Autorisierungsheadern)
• Andere Clients unter https://modelcontextprotocol.io/clients
• Weitere Kunden unter https://glama.ai/mcp/clients

Wenn Sie Akteure in den MCP-Server integriert haben, können Sie Folgendes fragen:

• „Durchsuchen Sie das Internet und fassen Sie aktuelle Trends zu KI-Agenten zusammen.“
• „Finden Sie die 10 besten italienischen Restaurants in San Francisco“
• "Finden und analysieren Sie das Instagram-Profil von The Rock"
• „Stellen Sie eine Schritt-für-Schritt-Anleitung zur Verwendung des Model Context Protocol mit Quell-URLs bereit.“
• „Welche Apify-Akteure kann ich verwenden?“

Das folgende Bild zeigt, wie der Apify MCP-Server mit der Apify-Plattform und KI-Clients interagiert:

Mit dem MCP Tester-Client können Sie Akteure dynamisch laden. Dies wird von anderen MCP-Clients jedoch noch nicht unterstützt. Wir planen außerdem, weitere Funktionen hinzuzufügen. Weitere Informationen finden Sie in der Roadmap .

🔄 Was ist das Model Context Protocol?

Das Model Context Protocol (MCP) ermöglicht KI-Anwendungen (und KI-Agenten) wie Claude Desktop die Verbindung mit externen Tools und Datenquellen. MCP ist ein offenes Protokoll, das sichere, kontrollierte Interaktionen zwischen KI-Anwendungen, KI-Agenten und lokalen oder Remote-Ressourcen ermöglicht.

Weitere Informationen finden Sie auf der Website des Model Context Protocol oder im Blogbeitrag „Was ist MCP und warum ist es wichtig?“ .

🤖 In welcher Beziehung steht der MCP-Server zu KI-Agenten?

Der Apify MCP-Server stellt die Akteure von Apify über das MCP-Protokoll bereit und ermöglicht KI-Agenten oder Frameworks, die das MCP-Protokoll implementieren, den Zugriff auf alle Apify-Akteure als Tools für die Datenextraktion, Websuche und andere Aufgaben.

Um mehr über KI-Agenten zu erfahren, lesen Sie unseren Blogbeitrag: Was sind KI-Agenten? und stöbern Sie in der kuratierten KI-Agenten-Sammlung von Apify. Möchten Sie Ihren eigenen KI-Agenten auf Apify erstellen und monetarisieren? Sehen Sie sich unsere Schritt-für-Schritt-Anleitung zum Erstellen, Veröffentlichen und Monetarisieren von KI-Agenten auf der Apify-Plattform an.

🧱 Komponenten

Werkzeuge

Schauspieler

Jeder Apify-Akteur kann als Werkzeug verwendet werden. Standardmäßig ist der Server mit den unten angegebenen Akteuren vorkonfiguriert. Dies kann jedoch durch die Eingabe von Akteuren überschrieben werden.

Der MCP-Server lädt das Actor-Eingabeschema und erstellt die entsprechenden MCP-Tools. Siehe dieses Beispiel eines Eingabeschemas für den RAG-Webbrowser .

Der Toolname muss immer der vollständige Name des Akteurs sein, z. B. apify/rag-web-browser . Die Argumente für ein MCP-Tool stellen die Eingabeparameter des Akteurs dar. Für den Akteur apify/rag-web-browser lauten die Argumente beispielsweise:

Sie müssen weder die Eingabeparameter noch den aufzurufenden Akteur angeben; alles wird von einem LLM verwaltet. Beim Aufruf eines Tools werden die Argumente automatisch vom LLM an den Akteur übergeben. Eine Liste der verfügbaren Argumente finden Sie in der Dokumentation des jeweiligen Akteurs.

Hilfswerkzeuge

Der Server bietet eine Reihe von Hilfstools zum Auffinden verfügbarer Akteure und zum Abrufen ihrer Details:

• get-actor-details : Ruft Dokumentation, Eingabeschema und Details zu einem bestimmten Akteur ab.
• discover-actors : Sucht anhand von Schlüsselwörtern nach relevanten Schauspielern und gibt deren Details zurück.

Es gibt auch Tools zum Verwalten der verfügbaren Toolliste. Das dynamische Hinzufügen und Entfernen von Tools erfordert jedoch, dass der MCP-Client die Toolliste aktualisieren kann (Handle ToolListChangedNotificationSchema ), was normalerweise nicht unterstützt wird.

Sie können diese Funktionalität mit dem Apify Tester MCP Client Actor ausprobieren. Um sie zu aktivieren, setzen Sie den Parameter enableActorAutoLoading .

• add-actor-as-tool : Fügt einen Akteur mit Namen zur Liste der verfügbaren Tools hinzu, ohne ihn auszuführen. Für die spätere Ausführung ist die Zustimmung des Benutzers erforderlich.
• remove-actor-from-tool : Entfernt einen Akteur anhand seines Namens aus der Liste der verfügbaren Tools, wenn er nicht mehr benötigt wird.

Eingabeaufforderung und Ressourcen

Der Server stellt keine Ressourcen und Eingabeaufforderungen bereit. Wir planen, den Datensatz und den Schlüsselwertspeicher von Apify zukünftig als Ressourcen hinzuzufügen.

⚙️ Verwendung

Der Apify MCP-Server kann auf zwei Arten verwendet werden: als Apify-Akteur, der auf der Apify-Plattform ausgeführt wird, oder als lokaler Server, der auf Ihrem Computer ausgeführt wird.

🇦 MCP-Server-Akteur

Standby-Webserver

Der Actor läuft im Standby-Modus mit einem HTTP-Webserver, der Anfragen empfängt und verarbeitet.

Um den Server mit Standardakteuren zu starten, senden Sie eine HTTP-GET-Anfrage mit Ihrem Apify-API-Token an die folgende URL:

Es ist auch möglich, den MCP-Server mit einem anderen Satz von Akteuren zu starten. Erstellen Sie dazu eine Aufgabe und geben Sie die Liste der Akteure an, die Sie verwenden möchten.

Führen Sie dann die Aufgabe im Standby-Modus mit den ausgewählten Akteuren aus:

Eine Liste aller verfügbaren Akteure finden Sie im Apify Store .

💬 Interagieren Sie mit dem MCP-Server über SSE

Sobald der Server läuft, können Sie mit Server-Sent Events (SSE) interagieren, um Nachrichten an den Server zu senden und Antworten zu erhalten. Am einfachsten geht das mit dem Tester MCP Client auf Apify.

Claude Desktop unterstützt derzeit keine SSE-Unterstützung, kann aber mit Stdio-Transport verwendet werden. Weitere Informationen finden Sie unter MCP-Server auf einem lokalen Host . Hinweis: Bei der kostenlosen Version von Claude Desktop kann es zeitweise zu Verbindungsproblemen mit dem Server kommen.

In den Clienteinstellungen müssen Sie die Serverkonfiguration angeben:

Alternativ können Sie das Skript clientSse.ts verwenden oder den Server mit curl </>-Befehlen testen.

1. Initiieren Sie Server-Sent-Events (SSE), indem Sie eine GET-Anfrage an die folgende URL senden:
   curl https://actors-mcp-server.apify.actor/sse?token=<APIFY_TOKEN>
   Der Server antwortet mit einer sessionId , die Sie zum Senden von Nachrichten an den Server verwenden können:
   event: endpoint data: /message?sessionId=a1b
2. Senden Sie eine Nachricht an den Server, indem Sie eine POST-Anfrage mit der sessionId stellen:
   curl -X POST "https://actors-mcp-server.apify.actor/message?token=<APIFY_TOKEN>&session_id=a1b" -H "Content-Type: application/json" -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "arguments": { "searchStringsArray": ["restaurants in San Francisco"], "maxCrawledPlacesPerSearch": 3 }, "name": "lukaskrivka/google-maps-with-contact-details" } }'
   Der MCP-Server startet den Akteur lukaskrivka/google-maps-with-contact-details mit den angegebenen Argumenten als Eingabeparameter. Auf diese POST-Anfrage antwortet der Server mit:
   Accepted
3. Empfangen Sie die Antwort. Der Server ruft den angegebenen Akteur als Tool mit den angegebenen Abfrageparametern auf und sendet die Antwort über SSE an den Client zurück. Die Antwort wird als JSON-Text zurückgegeben.
   event: message data: {"result":{"content":[{"type":"text","text":"{\"searchString\":\"restaurants in San Francisco\",\"rank\":1,\"title\":\"Gary Danko\",\"description\":\"Renowned chef Gary Danko's fixed-price menus of American cuisine ... \",\"price\":\"$100+\"...}}]}}

⾕ MCP-Server auf einem lokalen Host

Sie können den Apify MCP-Server auf Ihrem lokalen Rechner ausführen, indem Sie ihn mit Claude Desktop oder einem anderen MCP-Client konfigurieren. Sie können den Server auch mit Smithery automatisch installieren.

Voraussetzungen

• MacOS oder Windows
• Die neueste Version von Claude Desktop muss installiert sein (oder ein anderer MCP-Client)
• Node.js (v18 oder höher)
• Apify API-Token ( APIFY_TOKEN )

Stellen Sie sicher, dass Sie den node und npx ordnungsgemäß installiert haben:

Wenn nicht, befolgen Sie diese Anleitung zur Installation von Node.js: Herunterladen und Installieren von Node.js und npm .

Claude Desktop

So konfigurieren Sie Claude Desktop für den MCP-Server: Eine ausführliche Anleitung finden Sie im Claude Desktop-Benutzerhandbuch oder im Video-Tutorial .

1. Claude für Desktop herunterladen
   • Verfügbar für Windows und macOS.
   • Linux-Benutzer können mit diesem inoffiziellen Build-Skript ein Debian-Paket erstellen.
2. Öffnen Sie die Claude Desktop-App und aktivieren Sie den Entwicklermodus in der Menüleiste oben links.
3. Öffnen Sie nach der Aktivierung die Einstellungen (ebenfalls über die Menüleiste oben links) und navigieren Sie zu den Entwickleroptionen , wo Sie die Schaltfläche „Konfiguration bearbeiten“ finden.
4. Öffnen Sie die Konfigurationsdatei und bearbeiten Sie die folgende Datei:
   • Unter macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
   • Unter Windows: %APPDATA%/Claude/claude_desktop_config.json
   • Unter Linux: ~/.config/Claude/claude_desktop_config.json
   { "mcpServers": { "actors-mcp-server": { "command": "npx", "args": ["-y", "@apify/actors-mcp-server"], "env": { "APIFY_TOKEN": "your-apify-token" } } } }

   Alternativ können Sie das Argument actors verwenden, um einen oder mehrere Apify-Akteure auszuwählen:

   { "mcpServers": { "actors-mcp-server": { "command": "npx", "args": [ "-y", "@apify/actors-mcp-server", "--actors", "lukaskrivka/google-maps-with-contact-details,apify/instagram-scraper" ], "env": { "APIFY_TOKEN": "your-apify-token" } } } }
5. Starten Sie Claude Desktop neu
   • Beenden Sie Claude Desktop vollständig (stellen Sie sicher, dass es nicht nur minimiert oder geschlossen ist).
   • Starten Sie Claude Desktop neu.
   • Suchen Sie nach dem Symbol 🔌, um zu bestätigen, dass der Actors MCP-Server verbunden ist.
6. Öffnen Sie den Claude Desktop-Chat und fragen Sie: „Welche Apify-Akteure kann ich verwenden?“
7. BeispieleSie können Claude bitten, Aufgaben auszuführen, beispielsweise:
   Find and analyze recent research papers about LLMs. Find the top 10 best Italian restaurants in San Francisco. Find and analyze the Instagram profile of The Rock.

VS Code

Klicken Sie für die Ein-Klick-Installation auf eine der folgenden Installationsschaltflächen:

Manuelle Installation

Sie können den Apify MCP-Server manuell in VS Code installieren. Klicken Sie zunächst auf eine der Installationsschaltflächen oben in diesem Abschnitt, um die Installation mit einem Klick durchzuführen.

Alternativ können Sie den folgenden JSON-Block zu Ihrer Benutzereinstellungsdatei (JSON) in VS Code hinzufügen. Drücken Sie dazu Ctrl + Shift + P und geben Sie Preferences: Open User Settings (JSON) ein.

Optional können Sie es einer Datei namens .vscode/mcp.json in Ihrem Arbeitsbereich hinzufügen – lassen Sie einfach den mcp {} der obersten Ebene weg. Dadurch können Sie die Konfiguration mit anderen teilen.

Wenn Sie angeben möchten, welche Akteure geladen werden sollen, können Sie das Argument --actors hinzufügen:

VS Code

Klicken Sie für die Ein-Klick-Installation auf eine der folgenden Installationsschaltflächen:

Manuelle Installation

Sie können den Apify MCP-Server manuell in VS Code installieren. Klicken Sie zunächst auf eine der Installationsschaltflächen oben in diesem Abschnitt, um die Installation mit einem Klick durchzuführen.

Alternativ können Sie den folgenden JSON-Block zu Ihrer Benutzereinstellungsdatei (JSON) in VS Code hinzufügen. Drücken Sie dazu Ctrl + Shift + P und geben Sie Preferences: Open User Settings (JSON) ein.

Optional können Sie es einer Datei namens .vscode/mcp.json in Ihrem Arbeitsbereich hinzufügen – lassen Sie einfach den mcp {} der obersten Ebene weg. Dadurch können Sie die Konfiguration mit anderen teilen.

Wenn Sie angeben möchten, welche Akteure geladen werden sollen, können Sie das Argument --actors hinzufügen:

Debuggen des NPM-Pakets @apify/actors-mcp-server mit @modelcontextprotocol/inspector

Verwenden Sie zum Debuggen des Servers das MCP Inspector- Tool:

Installation über Smithery

So installieren Sie den Apify Actors MCP Server für Claude Desktop automatisch über Smithery :

Stdio-Clients

Erstellen Sie eine Umgebungsdatei .env mit folgendem Inhalt:

Im Verzeichnis examples finden Sie einen Beispielclient zur Interaktion mit dem Server über die Standardeingabe/-ausgabe (stdio):

• clientStdio.ts Dieses Client-Skript startet den MCP-Server mit zwei angegebenen Akteuren. Anschließend ruft es das Tool apify/rag-web-browser mit einer Abfrage auf und gibt das Ergebnis aus. Es zeigt, wie man sich mit dem MCP-Server verbindet, verfügbare Tools auflistet und ein bestimmtes Tool per stdio-Transport aufruft.
  node dist/examples/clientStdio.js

👷🏼 Entwicklung

Voraussetzungen

• Node.js (v18 oder höher)
• Python 3.9 oder höher

Erstellen Sie eine Umgebungsdatei .env mit folgendem Inhalt:

Erstellen Sie das Actor-MCP-Server-Paket:

Lokaler Client (SSE)

Um den Server mit dem SSE-Transport zu testen, können Sie das Skript examples/clientSse.ts verwenden: Derzeit unterstützt der Node.js-Client keine Verbindung zu einem Remote-Server mit benutzerdefinierten Headern. Sie müssen die URL im Skript in die URL Ihres lokalen Servers ändern.

Debuggen

Da MCP-Server über Standard-Ein-/Ausgabe (stdio) arbeiten, kann das Debuggen eine Herausforderung darstellen. Für optimale Ergebnisse beim Debuggen verwenden Sie den MCP Inspector .

Sie können den MCP Inspector über npm mit diesem Befehl starten:

Beim Start zeigt der Inspector eine URL an, auf die Sie in Ihrem Browser zugreifen können, um mit dem Debuggen zu beginnen.

ⓘ Einschränkungen und Feedback

Das Actor-Eingabeschema wird so verarbeitet, dass es mit den meisten MCP-Clients kompatibel ist und gleichzeitig den JSON-Schema- Standards entspricht. Die Verarbeitung umfasst:

• Beschreibungen werden auf 500 Zeichen gekürzt (wie in MAX_DESCRIPTION_LENGTH definiert).
• Enumerationsfelder werden für alle Elemente auf eine maximale Gesamtlänge von 200 Zeichen gekürzt (wie in ACTOR_ENUM_MAX_LENGTH definiert).
• Erforderliche Felder sind in ihren Beschreibungen ausdrücklich mit dem Präfix „ERFORDERLICH“ gekennzeichnet, um die Kompatibilität mit Frameworks zu gewährleisten, die das JSON-Schema möglicherweise nicht richtig verarbeiten.
• Für Sonderfälle wie die Proxy-Konfiguration und Anforderungslistenquellen werden verschachtelte Eigenschaften erstellt, um eine korrekte Eingabestruktur sicherzustellen.
• Array-Elementtypen werden abgeleitet, wenn sie nicht explizit im Schema definiert sind. Dabei wird eine Prioritätsreihenfolge verwendet: expliziter Typ in Elementen > Vorfülltyp > Standardwerttyp > Editortyp.
• Den Eigenschaftsbeschreibungen werden Enumerationswerte und Beispiele hinzugefügt, um die Sichtbarkeit sicherzustellen, auch wenn der Client das JSON-Schema nicht vollständig unterstützt.

Der Arbeitsspeicher für jeden Akteur ist auf 4 GB begrenzt. Für kostenlose Benutzer gilt ein Limit von 8 GB. Für die Ausführung Actors-MCP-Server müssen 128 MB zugewiesen werden.

Wenn Sie andere Funktionen benötigen oder Feedback haben, senden Sie ein Problem in der Apify-Konsole, um uns dies mitzuteilen.

🚀 Roadmap (März 2025)

• Fügen Sie den Datensatz und den Schlüssel-Wert-Speicher von Apify als Ressourcen hinzu.
• Fügen Sie Tools wie Actor-Protokolle und Actor-Läufe zum Debuggen hinzu.

🐛 Fehlerbehebung

• Stellen Sie sicher, dass der node installiert ist, indem Sie node -v ausführen.
• Stellen Sie sicher, dass Sie die Umgebungsvariable APIFY_TOKEN festgelegt haben
• Verwenden Sie immer die neueste Version des MCP-Servers, indem Sie @apify/actors-mcp-server@latest festlegen

📚 Mehr erfahren

• Modellkontextprotokoll
• Was sind KI-Agenten?
• Was ist MCP und warum ist es wichtig?
• So verwenden Sie MCP mit Apify Actors
• Tester MCP Client
• KI-Agent-Workflow: Erstellen eines Agenten zum Abfragen von Apify-Datensätzen
• MCP-Client-Entwicklungshandbuch
• So erstellen und monetarisieren Sie einen KI-Agenten auf Apify