Verbinden Sie KI-Agenten mit listingsAPI MCP

Am gehosteten MCP-Server lesen und bearbeiten Claude, ChatGPT, Cursor oder Gemini Ihre Standorte, Einträge und Bewertungen mit denselben Tools wie Sie.

Die Listings API stellt unter https://listingsapi.com/mcp einen Server für das Model Context Protocol (MCP) bereit. Sie müssen nichts installieren oder ausführen. Ein KI-Assistent, der MCP unterstützt, verbindet sich mit dieser URL, erkennt ein Tool pro REST-Endpunkt sowie einige Dokumentationstools und ruft sie für Ihr Konto auf. Diese Anleitung beschreibt, wie Sie die gängigen Clients verbinden und anschließend die Verbindung überprüfen.

1. Verstehen, worauf der Agent Zugriff erhält

Der Server stellt etwas mehr als 60 Tools bereit, von denen etwa zwei Drittel nur lesend zugreifen. Die Namen entsprechen den REST-Ressourcen, sodass locations_search, listings_premium, reviews_respond und posts_create_social dieselben Funktionen wie die entsprechenden Endpunkte ausführen, mit denselben Parametern und derselben Antwortstruktur. Mit den drei Dokumentationstools search_docs, get_doc und get_endpoint kann der Assistent eine Seite oder die Spezifikation eines Endpunkts nachschlagen, statt die Struktur der Nutzdaten zu erraten.

Tool-GruppeBeispieleErforderliche Berechtigungen
Standortelocations_all, locations_search, locations_create, locations_updateRead zum Abfragen, Write zum Erstellen und Aktualisieren
Einträgelistings_premium, listings_duplicates, listings_mark_duplicateRead, Write zum Markieren von Duplikaten
Verbundene Kontenconnected_accounts_list, connected_accounts_listings, connected_accounts_connect_listingRead, Write zum Verbinden und Importieren
Bewertungenreviews_list, reviews_get, reviews_respond, reviews_analyticsRead, Write zum Antworten
Beiträgeposts_social_post_view, posts_create_socialRead, Write zum Veröffentlichen
Analysenanalytics_google, analytics_facebook, analytics_bing (veraltet, gibt keine Daten zurück)Read
Kontowhoami, get_usage, get_subscription, recent_errorsRead
Dokumentationsearch_docs, get_doc, get_endpoint, list_endpointsKeine

Destruktive Vorgänge wie das Löschen eines Beitrags oder das Archivieren eines Standorts werden nicht als Tools bereitgestellt. Verwenden Sie dafür die REST-API oder ein SDK, damit ein Assistent nicht eigenständig Daten entfernen kann.

2. Anmeldemethode für den Client wählen

Jeder Client authentifiziert sich auf eine von zwei Arten. Beide verwenden serverseitig letztlich denselben API-Schlüssel, sodass die Begrenzungen der Anfragerate und die Nutzungsberichte identisch sind.

MethodeWas Sie einfügenAm besten geeignet für
API-Schlüssel im HeaderAuthorization: API <your key> als statischer HeaderCLIs und Editoren, bei denen Sie die Konfigurationsdatei bearbeiten können
OAuth 2.0Nichts. Der Client öffnet einen Browser, Sie melden sich an und genehmigen read oder read writeGehostete Assistenten wie Claude und ChatGPT oder alle, die keinen direkten Zugriff auf einen Schlüssel haben sollten

OAuth verwendet den Authorization Code Flow mit PKCE und dynamischer Client-Registrierung, sodass ein Client keine vorab ausgestellten Zugangsdaten benötigt. Die Metadaten finden Sie unter https://listingsapi.com/.well-known/oauth-authorization-server. Die Scopes sind read und write; ein Client, der keinen Scope anfordert, erhält read. Jede Genehmigung erstellt einen eigenen Schlüssel für diese Verbindung, den Sie unter /dashboard/keys wie jeden anderen Schlüssel widerrufen können.

3. Claude verbinden

Claude.ai und Claude Desktop. Der Server ist im Konnektorverzeichnis aufgeführt. Am schnellsten öffnen Sie daher https://claude.ai/directory/listings-api und klicken auf Connect (Verbinden). Claude führt den OAuth-Vorgang aus, Sie genehmigen die Scopes, und die Tools stehen in jedem Chat zur Verfügung, in dem Sie den Konnektor über die Schaltfläche + und anschließend Connectors (Konnektoren) aktivieren.

Wenn Sie ihn lieber per URL hinzufügen möchten, gehen Sie zu Customize (Anpassen) und dann zu Connectors (Konnektoren), klicken Sie auf + und Add custom connector (Benutzerdefinierten Konnektor hinzufügen), fügen Sie https://listingsapi.com/mcp ein und klicken Sie auf Add (Hinzufügen). Lassen Sie Advanced settings (Erweiterte Einstellungen) leer; der Server registriert Claude automatisch als Client. In den Tarifen Team und Enterprise fügt ein Inhaber den Konnektor unter Organization settings (Organisationseinstellungen) und dann Connectors (Konnektoren) hinzu, und die Mitglieder klicken anschließend beim Konnektor auf Connect (Verbinden). Claude stellt die Verbindung von den Servern von Anthropic aus her, nicht von Ihrem Rechner aus, weshalb die gehostete URL wichtig ist.

Claude Code. Ein Befehl fügt den Server mit Ihrem Schlüssel hinzu:

Claude Code
claude mcp add --transport http listingsapi https://listingsapi.com/mcp \--header "Authorization: API $LISTINGSAPI_KEY"

Lassen Sie das Flag --header weg und führen Sie /mcp in Claude Code aus, um sich stattdessen über den Browser anzumelden. Verwenden Sie --scope project, um den Server in einer vom gesamten Team gemeinsam genutzten .mcp.json zu hinterlegen und diese zu committen; committen Sie dabei keinen Schlüssel.

4. ChatGPT verbinden

ChatGPT verbindet sich über einen benutzerdefinierten Konnektor mit entfernten MCP-Servern, sobald Developer mode (Entwicklermodus) aktiviert ist. Diese Funktion ist in den Tarifen Plus, Pro, Business, Enterprise und Edu verfügbar, nicht im kostenlosen Tarif.

  1. Öffnen Sie Settings (Einstellungen) über Ihr Profilmenü und aktivieren Sie Developer mode (Entwicklermodus). Je nach Version befindet sich die Option unter Apps & Connectors (Apps und Konnektoren) oder Security and login (Sicherheit und Anmeldung).
  2. Klicken Sie auf der Konnektorenseite (in aktuellen Versionen als Plugins (Erweiterungen) bezeichnet) auf + oder Create (Erstellen).
  3. Geben Sie einen Namen ein, fügen Sie https://listingsapi.com/mcp als Server-URL ein und wählen Sie OAuth zur Authentifizierung. Speichern Sie die Einstellungen.
  4. ChatGPT öffnet die Anmeldeseite. Genehmigen Sie read oder read write.
  5. Öffnen Sie in einem neuen Chat das Tool-Menü, wählen Sie den Konnektor aus und prüfen Sie, ob er mit seinen Tools angezeigt wird. Für die Ausführung schreibender Tools ist weiterhin eine Bestätigung erforderlich.

Codex CLI. Der Terminal-Agent von OpenAI liest MCP-Server aus ~/.codex/config.toml. Codex startet OAuth für HTTP-Server selbstständig und berücksichtigt die vom Server angegebenen Scopes, daher ist die Header-Zeile optional:

~/.codex/config.toml
[mcp_servers.listingsapi]url = "https://listingsapi.com/mcp"http_headers = { "Authorization" = "API <your key>" }

5. Cursor verbinden

Die Dashboard-Seite unter /dashboard/mcp enthält die Schaltfläche Add to Cursor (Zu Cursor hinzufügen). Sie öffnet einen Installationslink für Cursor, in dem die Server-URL und Ihr Schlüssel bereits eingetragen sind, sodass ein Klick die Einrichtung abschließt.

Für die manuelle Konfiguration fügen Sie den Server in ~/.cursor/mcp.json für alle Projekte oder in .cursor/mcp.json innerhalb eines einzelnen Repositorys hinzu:

~/.cursor/mcp.json
{"mcpServers": {  "listingsapi": {    "url": "https://listingsapi.com/mcp",    "headers": {      "Authorization": "API <your key>"    }  }}}

Entfernen Sie den Block headers, um sich stattdessen mit OAuth anzumelden: Cursor zeigt unter Settings (Einstellungen) und anschließend MCP am Servereintrag die Schaltfläche Connect (Verbinden) an und öffnet den Anmeldevorgang im Browser. Committen Sie niemals einen Schlüssel in einer projektbezogenen .cursor/mcp.json; verwenden Sie für gemeinsam genutzte Repositorys die globale Datei oder OAuth.

6. Gemini verbinden

Gemini CLI. Der Terminal-Agent von Google liest entfernte Server aus ~/.gemini/settings.json (oder .gemini/settings.json innerhalb eines Projekts). Verwenden Sie httpUrl, nicht url, damit er den Transporttyp Streamable HTTP auswählt:

~/.gemini/settings.json
{"mcpServers": {  "listingsapi": {    "httpUrl": "https://listingsapi.com/mcp",    "headers": {      "Authorization": "API <your key>"    },    "timeout": 30000  }}}

Für OAuth ersetzen Sie den Block headers durch "oauth": { "enabled": true }, starten Sie die CLI und führen Sie /mcp auth listingsapi aus. Sie können jederzeit /mcp ausführen, um den Server, seinen Verbindungsstatus und die von ihm erkannten Tools aufzulisten.

Gemini-App. Die Gemini-App für Endnutzer bietet keine Einstellung für benutzerdefinierte Konnektoren. Benutzerdefinierte MCP-Server stehen Teamadministratoren der Gemini Enterprise Business Edition zur Verfügung: Melden Sie sich unter business.gemini.google an, öffnen Sie Settings & help (Einstellungen und Hilfe), dann Manage team (Team verwalten) und Connected apps (Verbundene Apps) und klicken Sie auf Add MCP Server (MCP-Server hinzufügen). Fügen Sie https://listingsapi.com/mcp als URL ein. Das Formular fragt nach OAuth-Angaben: Die Autorisierungs-URL ist https://listingsapi.com/oauth/authorize, die Token-URL ist https://listingsapi.com/oauth/token und die Scopes sind read write. Außerdem werden eine Client-ID und ein Client-Secret abgefragt. Dieser Server registriert öffentliche PKCE-Clients ohne Secret. Registrieren Sie daher einen solchen Client mit der im Formular angezeigten Weiterleitungs-URL und lassen Sie das Secret-Feld leer, sofern das Formular dies zulässt:

Register an OAuth client
curl -s https://listingsapi.com/oauth/register \-H "Content-Type: application/json" \-d '{  "client_name": "Gemini Business",  "redirect_uris": ["<redirect URL shown in the Gemini form>"],  "grant_types": ["authorization_code", "refresh_token"],  "token_endpoint_auth_method": "none"}'

Die Antwort enthält client_id. Wenn Ihr Gemini-Formular zwingend ein Secret verlangt, verwenden Sie den oben beschriebenen Weg über die Gemini CLI oder entwickeln Sie stattdessen mit der Gemini API.

Entwicklung mit der Gemini API. Das SDK der Gemini API akzeptiert eine MCP-Clientsitzung als Tool, sodass ein Skript einem Gemini-Modell dieselben Tools bereitstellen kann:

gemini_agent.py
import asyncio, osfrom google import genaifrom mcp import ClientSessionfrom mcp.client.streamable_http import streamablehttp_client HEADERS = {"Authorization": "API " + os.environ["LISTINGSAPI_KEY"]} async def main():  gemini = genai.Client()  async with streamablehttp_client("https://listingsapi.com/mcp", headers=HEADERS) as (r, w, _):      async with ClientSession(r, w) as session:          await session.initialize()          reply = await gemini.aio.models.generate_content(              model="gemini-2.5-pro",              contents="Which of my locations have a Google listing that is not live yet?",              config=genai.types.GenerateContentConfig(tools=[session]),          )          print(reply.text) asyncio.run(main())

7. Verbindung prüfen

Bevor Sie sich auf den Assistenten verlassen, prüfen Sie, ob der Server Ihnen direkt antwortet. Zum Ermitteln der Tools ist kein Schlüssel erforderlich, daher ist dieser Aufruf mit jedem Client erfolgreich, der die URL erreichen kann:

List the tools
curl -s https://listingsapi.com/mcp \-H "Content-Type: application/json" \-H "Accept: application/json, text/event-stream" \-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head -c 400

Bitten Sie den Assistenten anschließend um etwas, das einen Zugriff auf Ihr Konto erfordert:

Verwenden Sie die listingsapi-Tools, um meinen Tarif anzuzeigen, meine Standorte zu zählen und meine API-Nutzung für diesen Monat anzugeben.

Bei einer funktionierenden Verbindung werden Ihr Tarif und Ihr Zugriffsstatus aus whoami, Standortdaten aus locations_all und Nutzungszahlen aus get_usage zurückgegeben. Ein falscher oder abgelaufener Schlüssel führt beim ersten Tool-Aufruf zu einem Unauthenticated-Fehler, nicht beim Ermitteln der Tools.

Geeignete erste Prompts, sobald die Verbindung funktioniert:

  • "Listen Sie meine Standorte auf, deren Einträge Fehler aufweisen, und fassen Sie jeden Fehler zusammen."
  • "Zeigen Sie unbeantwortete Bewertungen, die in den letzten 7 Tagen eingegangen sind, und entwerfen Sie für jede eine Antwort. Senden Sie die Antworten noch nicht."
  • "Vergleichen Sie die Google-Profilanalysen für Standort 1800289 für die letzten zwei Monate."
  • "Lesen Sie die Schnittstellenspezifikation des create-location-Endpunkts und fügen Sie dann diesen Standort hinzu: ..."

Die listingsAPI-Skills für Agenten hinzufügen

Skills sind Anweisungen, die ein Agent bei einer passenden Aufgabe lädt, damit er einem getesteten Ablauf folgt, statt selbst einen zu entwickeln. Sie arbeiten mit dem MCP-Server zusammen: Der Server führt die Aufrufe aus, und der Skill legt fest, welche Aufrufe in welcher Reihenfolge ausgeführt werden. Fünf listingsAPI-Skills aus dem öffentlichen listingsapi-mcp-Repository sind auf skills.sh veröffentlicht:

SkillFunktion
listingsapi-integrationIntegriert die Listings API in Ihre Anwendung: Authentifizierung, ein erster Lesezugriff, Standorte, Plattformverbindungen und Synchronisierungsstatus, mit REST- oder SDK-Code.
listingsapi-listing-auditPrüft Standorte und ihre Einträge auf Synchronisierungsstatus, Live-Links und mögliche Duplikate und schlägt anschließend Korrekturen vor. Führt nur Lesezugriffe aus, bis Sie eine Korrektur genehmigen.
listingsapi-review-managementErstellt eine Warteschlange für Bewertungen, priorisiert unbeantwortete Bewertungen, entwirft Antworten und veröffentlicht nur die von Ihnen genehmigten Antworten.
listingsapi-multi-location-postingBereitet Ankündigungen, Veranstaltungen und Angebote für die von Ihnen ausgewählten Standorte vor, veröffentlicht sie auf Google Business Profile und Facebook und prüft anschließend jedes Ergebnis.
listingsapi-performance-reportingErstellt Berichte zu Leistung und Bewertungen über Ihre Standorte hinweg und greift dabei nur lesend auf die Daten zu.

Installieren Sie alle fünf mit der Skills CLI in Ihrem Projekt:

All skills
npx skills add listings-api/listingsapi-mcp

Oder installieren Sie einen Skill anhand seines Namens und wählen Sie den Agenten mit -a aus:

One skill, for Claude Code
npx skills add listings-api/listingsapi-mcp --skill listingsapi-integration -a claude-code

Verwenden Sie für diese Agenten -a cursor oder -a codex und fügen Sie -g hinzu, um die Skills für alle Projekte statt nur für das aktuelle zu installieren.

listingsAPI in Verzeichnissen für KI-Tools finden

Derselbe Server ist zusammen mit dem listingsAPI-Skill für Agenten in diesen Verzeichnissen aufgeführt. Installieren Sie ihn aus dem Verzeichnis, das Ihr Client bereits verwendet. Jeder MCP-Server-Eintrag verweist auf https://listingsapi.com/mcp.

VerzeichnisAufgeführte Komponenten
Claude-KonnektorverzeichnisDer MCP-Server als Claude-Konnektor. Klicken Sie auf Connect (Verbinden) und melden Sie sich an.
Offizielle MCP-RegistryDer MCP-Server, registriert als com.listingsapi/mcp.
Cursor DirectoryDer MCP-Server als Cursor-Plugin.
GlamaDer MCP-Server.
SmitheryDer MCP-Server.
MCP.soDer MCP-Server.
mcpservers.orgDer MCP-Server.
ClawHub (OpenClaw)Der listingsAPI-Skill für Agenten.
skills.shDer listingsAPI-Skill für Agenten.

Fehlerbehebung

SymptomUrsacheLösung
401 beim ersten Tool-AufrufDer Schlüssel wurde falsch eingegeben oder widerrufen, oder der Header enthält nicht das exakte Wort API mit einem nachfolgenden LeerzeichenErstellen Sie den Schlüssel in /dashboard/keys neu und fügen Sie ihn als API <key> ein
SY90016 bei einem SchreibzugriffSchlüssel mit Lesezugriff oder Berechtigungsumfang readStellen Sie die Verbindung mit einem Schlüssel mit Schreibzugriff erneut her oder genehmigen Sie write
429 mit Retry-AfterDer Agent führt Aufrufe schneller aus, als Ihr Tarif erlaubtBitten Sie ihn, in kleineren Stapeln zu arbeiten; siehe Ratenbegrenzungen
Der Client meldet, dass er den Server nicht erreichen kannDer Client unterstützt nur stdio oder SSEVerwenden Sie einen Client, der Streamable HTTP unterstützt, oder die auf /dashboard/mcp gezeigte mcp-remote-Bridge
Ein in der Dokumentation genanntes Tool fehltDestruktive Tools werden nicht bereitgestelltVerwenden Sie REST oder ein SDK zum Archivieren und Löschen

Nächste Schritte