KI-Agenten mit listingsAPI MCP verbinden

Verbinden Sie Claude, ChatGPT, Cursor oder Gemini mit dem gehosteten MCP-Server: Standorte, Einträge und Bewertungen mit Ihren Tools lesen und bearbeiten.

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 diese für Ihr Konto auf. Diese Anleitung beschreibt, wie Sie die wichtigsten Clients verbinden und anschließend die Verbindung überprüfen.

1. Verstehen, welche Funktionen der Agent erhält

Der Server stellt etwas mehr als sechzig Tools bereit, von denen etwa zwei Drittel nur Lesezugriff bieten. Die Namen richten sich nach den REST-Ressourcen. Daher führen locations_search, listings_premium, reviews_respond und posts_create_social dieselben Aktionen wie die zugehörigen Endpunkte aus, mit denselben Parametern und derselben Antwortstruktur. Mit den drei Dokumentationstools search_docs, get_doc und get_endpoint kann der Assistent eine Seite oder die Schnittstellenspezifikation eines Endpunkts nachschlagen, statt die Struktur der Nutzdaten zu erraten.

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 selbstständig Daten entfernen kann.

2. Anmeldemethode für den Client auswählen

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

OAuth verwendet den Authorization Code Flow mit PKCE und dynamischer Client-Registrierung, sodass ein Client keine vorab ausgestellten Zugangsdaten benötigt. Die Metadaten sind unter https://listingsapi.com/.well-known/oauth-authorization-server verfügbar. 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 durch, 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, öffnen Sie Customize (Anpassen), dann 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, woraufhin die Mitglieder beim Konnektor auf Connect (Verbinden) klicken. Claude stellt die Verbindung über die Server von Anthropic her, nicht über Ihren Rechner. Deshalb ist die gehostete URL wichtig.

Claude Code. Mit einem Befehl fügen Sie den Server mit Ihrem Schlüssel hinzu:

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 stellt über einen benutzerdefinierten Konnektor eine Verbindung zu entfernten MCP-Servern her, 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 finden Sie 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.
4. ChatGPT öffnet die Anmeldeseite. Genehmigen Sie read oder read write.
5. Öffnen Sie in einem neuen Chat das Werkzeugmenü, wählen Sie den Konnektor aus und prüfen Sie, ob er mit seinen Werkzeugen angezeigt wird. Schreibende Werkzeuge erfordern weiterhin eine Bestätigung.

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:

[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.

Um die Verbindung manuell zu konfigurieren, fügen Sie den Server für alle Projekte in ~/.cursor/mcp.json oder innerhalb eines einzelnen Repositorys in .cursor/mcp.json hinzu:

{"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), dann MCP, beim Servereintrag die Schaltfläche Connect (Verbinden) an und öffnet den Anmeldevorgang im Browser. Nehmen Sie niemals einen Schlüssel in einer projektbezogenen .cursor/mcp.json in einen Commit auf; verwenden Sie für gemeinsam genutzte Repositorys die globale Datei oder OAuth.

6. Gemini verbinden

Gemini CLI. Der Terminal-Agent von Google übernimmt entfernte Server aus ~/.gemini/settings.json (oder .gemini/settings.json in einem Projekt). Verwenden Sie httpUrl, nicht url, damit er den Transport über Streamable HTTP auswählt:

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

Ersetzen Sie für OAuth 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 erkannten Werkzeuge aufzulisten.

Gemini-App. Die Gemini-App für Privatnutzer 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 lautet https://listingsapi.com/oauth/authorize, die Token-URL lautet https://listingsapi.com/oauth/token und die Scopes sind read write. Außerdem werden eine Client-ID und ein Client-Secret abgefragt. Dieser Server stellt öffentliche PKCE-Clients ohne Secret aus. 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:

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.

Mit der Gemini API entwickeln. Das Gemini API SDK akzeptiert eine MCP-Clientsitzung als Werkzeug, sodass ein Skript einem Gemini-Modell dieselben Werkzeuge bereitstellen kann:

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. Für die Werkzeugerkennung ist kein Schlüssel erforderlich, daher gelingt dieser Aufruf mit jedem Client, der die URL erreichen kann:

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

Stellen Sie anschließend im Assistenten eine Anfrage, die einen Zugriff auf Ihr Konto erfordert:

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

Bei einer funktionierenden Verbindung erhalten Sie Ihren Tarif und Zugriffsstatus von whoami, Standortdaten von locations_all und Nutzungszahlen von get_usage. Ein falscher oder abgelaufener Schlüssel führt beim ersten Werkzeugaufruf zu einem Unauthenticated-Fehler, nicht bei der Werkzeugerkennung.

Geeignete erste Prompts, sobald die Verbindung funktioniert:

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

Die listingsAPI-Agenten-Skills hinzufügen

Skills sind Anweisungen, die ein Agent lädt, wenn sie zu einer Aufgabe passen, damit er einem erprobten Ablauf folgt, statt selbst einen zu entwickeln. Sie ergänzen den MCP-Server: Der Server führt die Aufrufe aus, und der Skill legt fest, welche Aufrufe in welcher Reihenfolge erfolgen. Fünf listingsAPI-Skills aus dem öffentlichen listingsapi-mcp-Repository sind auf skills.sh veröffentlicht:

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

npx skills add listings-api/listingsapi-mcp

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

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 Installation für alle Projekte statt nur für das aktuelle Projekt durchzuführen.

listingsAPI in Verzeichnissen für KI-Tools finden

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

Fehlerbehebung

Nächste Schritte

• Integrationsmethode wählen: Wann MCP geeignet ist und wann REST oder ein SDK die bessere Wahl ist.
• Ihren ersten API-Aufruf ausführen: Erstellen Sie einen Schlüssel und lernen Sie die Struktur der von den Tools zurückgegebenen Antworten kennen.
• Mit Webhooks auf Ereignisse reagieren: Lassen Sie die Plattform Ihren Agenten benachrichtigen, statt regelmäßig Abfragen durchzuführen.
• Authentifizierung und Fehlercodes erläutern die Codes, die der Assistent Ihnen meldet.