API- & MCP-Dokumentation
Was der Pushrank-MCP-Server bereitstellt und wie Sie ihn manuell über die API aufrufen.
Bereitgestellte Tools
Der Pushrank-MCP-Server stellt 49 Tools bereit. Alle Antworten sind auf die Projekte Ihrer Organisation beschränkt; die 26 Schreibaktionen sind unten gekennzeichnet. Nur die aufgeführten Parameter werden akzeptiert: Ein nicht deklarierter Parameter wird mit einer Fehlermeldung abgelehnt, die den Schlüssel nennt, und nie stillschweigend ignoriert.
whoamiZeigt den authentifizierten Nutzer, zugängliche Organisationen, gewährte Scopes, Credit-Guthaben und nützliche Pushrank-Links.
Parameter: Keine. Nur Lesezugriff, ohne zusätzlichen Scope.
list_projectsListet die Pushrank-Projekte auf, auf die der authentifizierte Nutzer Zugriff hat.
Parameter: limit (1–50, Standard 25).
get_project_overviewKompakte Übersicht eines Projekts: Traffic, Digest-Zusammenfassung und Statuszahlen.
Parameter: projectId.
get_seo_forecastSEO-Prognose eines Projekts, schreibgeschützt: die Schätzung von Pushrank (Schieberegler in Standardposition) mit Kurve, M6, M12, kumuliertem Gesamtwert, Kosten, Schwelle, Deckung, Berater-Vergleich, Annahmen und Herkunft, oder der Grund, warum sie nicht verfügbar ist. Gleicher Detaillierungsgrad wie in der App für das Konto. Eine Annahme, keine Garantie.
Parameter: projectId.
list_seo_opportunitiesRuft automatisch die vollständige Liste der SEO-Aktionen ab, die Ihrer Anfrage entsprechen (standardmäßig aktive), und leitet den Assistenten an, sie als Tabelle darzustellen. Umfang und Lebenszyklus-Status entsprechen der Ansicht „Aktionen“; die Antwort erläutert zudem, welche Aktionen dort ausgeblendet sind.
Parameter: projectId; optional: status (standardmäßig active | todo | in_progress | done | verified | still_present | ignored | all), type, severity, priority, source, query, pageUrl, priorityMin. Standardmäßig pagination=all; pagination=page aktiviert den technischen seitenweisen Zugriff mit page (Standard 1) und pageSize (Standard 10, maximal 25).
update_seo_opportunity_statusSchreiben · mcp:actions:writeAktualisiert den Workflow-Status einer oder mehrerer SEO-Chancen (bis zu 50 pro Aufruf) und liefert ein Ergebnis pro Chance: angewendet, bereits in diesem Status oder abgelehnt mit Grund. Erfordert den Scope mcp:actions:write.
Parameter: projectId, status; opportunityId für eine Chance oder opportunityIds (1 bis 50) für einen Stapel.
get_gsc_digestGibt den letzten abgeschlossenen GSC-Digest und den Status des letzten Versuchs zurück; erstellt keinen neuen Digest.
Parameter: projectId; kind (dashboard_digest | weekly_gsc | monthly_gsc, Standard dashboard_digest).
get_gsc_snapshotLiest nur gespeicherte Google-Search-Console-Snapshots; ruft GSC nie live ab.
Parameter: projectId, dimension (date | page | query | query_page | page_date); optional: period, compareTo (gleiche Dauer), pageUrl, offset, limit (max. 50).
list_articlesListet Artikel mit Scores, Qualitätsstatus und Veröffentlichungsmetadaten auf, ohne den vollständigen Inhalt.
Parameter: projectId; optional: status, search, limit (max. 25).
get_articleGibt einen vollständigen Artikel zurück: Inhalt, Meta, Qualitätsberichte, Veröffentlichungsprotokolle, verknüpfte Keywords, Chancen und Agent-Läufe.
Parameter: projectId, articleId.
get_article_generation_readinessPrüft vor der Generierung Kontingent, Vollständigkeit des Briefings, Kannibalisierung und SERP-Warnungen, ohne etwas zu erstellen.
Parameter: projectId, keyword, intent, articleType; optional: niche, languageCode.
generate_articleSchreiben · mcp:articles:generateStartet den regulären Workflow zur Artikelgenerierung mit Kontingenten und Sicherheitsprüfungen. Erfordert mcp:articles:generate.
Parameter: projectId, keyword, intent, idempotencyKey (UUID); optional: articleType, niche, languageCode, brief, opportunityId, acknowledgeWarnings.
get_workflow_statusLiest den Fortschritt einer Artikelgenerierung oder CMS-Veröffentlichung.
Parameter: projectId und genau eines von requestId oder articleId; optional: publicationJobId.
get_article_publication_readinessPrüft vor der Veröffentlichung Artikelinhalt, Qualität, CMS-Verbindung, Funktionen und Herkunft.
Parameter: projectId, articleId.
publish_article_to_cmsSchreiben · mcp:articles:publishVeröffentlicht oder aktualisiert den Artikel tatsächlich im verbundenen CMS. Erfordert mcp:articles:publish.
Parameter: projectId, articleId, idempotencyKey (UUID), confirmed=true; optional: acknowledgeQualityOverride.
list_content_planGibt den aktuellen Redaktionsplan und den Status jedes geplanten Themas zurück.
Parameter: projectId.
generate_article_from_plan_itemSchreiben · mcp:articles:generateStartet nach Bestätigung den regulären Generierungs-Workflow aus einem Planeintrag. Erfordert mcp:articles:generate.
Parameter: projectId, itemId, confirmed=true; optional: acknowledgeWarnings.
edit_articleSchreiben · mcp:articles:writeZeigt Artikeländerungen in der Vorschau an und wendet sie mit optimistischer Versionsprüfung an. Das Anwenden erfordert mcp:articles:write.
Parameter: projectId, articleId, mode, expectedUpdatedAt, changes (title, slug, content, metaDescription, faqData, ctaData, robotsConfig{index, follow, noSnippet, noArchive}, featuredImageAlt); confirmed=true zum Anwenden. Ein ctaData mit html "" oder blocks [] bleibt ohne CTA, auch mit URL; ein CTA ohne gültige URL wird nicht dargestellt.
get_article_performanceLiest die gespeicherte GSC-Performance der veröffentlichten Seite, ohne Google live abzufragen.
Parameter: projectId, articleId.
add_keywordsSchreiben · mcp:keywords:writeZeigt bis zu 100 Keywords in der Vorschau an und fügt sie dann der Strategie hinzu. Neue Keywords werden wie beim Hinzufügen im Dashboard angereichert (Volumen, Schwierigkeit, SERP, Intent), ohne Credit-Kosten, bei aktivem Abo. Ein zuvor entferntes Keyword wird wiederhergestellt. Das Anwenden erfordert mcp:keywords:write.
Parameter: projectId, mode, terms[], locale, intent; confirmed=true und idempotencyKey zum Anwenden.
update_keywordSchreiben · mcp:keywords:writeZeigt in der Vorschau an und überschreibt dann Intent, Status oder Prioritäts-Score eines Keywords. Das Anwenden erfordert mcp:keywords:write.
Parameter: projectId, mode, keywordId, changes (intent, status, priorityScore); confirmed=true und idempotencyKey zum Anwenden.
set_keyword_statusesSchreiben · mcp:keywords:writeZeigt in der Vorschau an und setzt dann einen Status für bis zu 100 Keywords. Das Anwenden erfordert mcp:keywords:write.
Parameter: projectId, mode, keywordIds[], status; confirmed=true und idempotencyKey zum Anwenden.
get_page_reanalysis_readinessPrüft URL, bekannte Seite, doppelte Arbeit und Credits, bevor die Analyse erneut ausgeführt wird.
Parameter: projectId, pageUrl.
reanalyze_pageSchreiben · mcp:analysis:runFührt die reguläre, Credit-basierte SEO-Analyse einer Seite erneut aus. Erfordert mcp:analysis:run.
Parameter: projectId, pageUrl, idempotencyKey, confirmed=true.
get_editorial_contextLiest den strukturierten redaktionellen Kontext, ohne interne RAG-Dokumente offenzulegen.
Parameter: projectId.
edit_editorial_contextSchreiben · mcp:editorial:writeZeigt den strukturierten redaktionellen Kontext in der Vorschau an und wendet ihn mit Versionsprüfung an. Das Anwenden erfordert mcp:editorial:write.
Parameter: projectId, mode, expectedUpdatedAt, changes (brandName, primaryOffer, audience, benefits, positioning, tone, proofs[]{claim, sourceUrl, excerpt}); confirmed=true zum Anwenden.
get_business_profileLiest das vollständige Unternehmensprofil: jeden Fakt mit Status, Herkunft und Entscheidung, Bereitschaft, fehlende Kernfelder und Legacy-Modus.
Parameter: projectId.
declare_business_factSchreiben · mcp:editorial:writeZeigt in der Vorschau an und erfasst dann einen Fakt im Unternehmensprofil (Angebot, Zielgruppe, Markt, Ziel, Regel, Einschränkung, Saisonalität oder Begriff). Bei einer bereits belegten Adresse wird der Wert ersetzt. Das Anwenden erfordert mcp:editorial:write.
Parameter: projectId, mode, expectedRevision, idempotencyKey, address, value; confirmed=true zum Anwenden.
replace_business_factSchreiben · mcp:editorial:writeZeigt in der Vorschau an und überschreibt dann den Wert eines Unternehmensfakts. Das Anwenden erfordert mcp:editorial:write.
Parameter: projectId, mode, expectedRevision, idempotencyKey, factId, value; confirmed=true zum Anwenden.
confirm_business_factSchreiben · mcp:editorial:writeZeigt in der Vorschau an und bestätigt dann einen vorgeschlagenen Unternehmensfakt. Das Anwenden erfordert mcp:editorial:write.
Parameter: projectId, mode, expectedRevision, idempotencyKey, factId; confirmed=true zum Anwenden.
reject_business_factSchreiben · mcp:editorial:writeEinen vorgeschlagenen oder bestätigten Unternehmensfakt in der Vorschau prüfen und dann ablehnen; er kann später wiederhergestellt werden. Das Anwenden erfordert mcp:editorial:write.
Parameter: projectId, mode, expectedRevision, idempotencyKey, factId, reason; confirmed=true zum Anwenden.
withdraw_business_factSchreiben · mcp:editorial:writeEinen Unternehmensfakt in der Vorschau prüfen und dann endgültig entfernen; er kann nicht wiederhergestellt werden. Das Anwenden erfordert mcp:editorial:write.
Parameter: projectId, mode, expectedRevision, idempotencyKey, factId, reason; confirmed=true zum Anwenden.
restore_business_factSchreiben · mcp:editorial:writeEinen abgelehnten Unternehmensfakt in der Vorschau prüfen und dann wieder auf „vorgeschlagen“ setzen. Das Anwenden erfordert mcp:editorial:write.
Parameter: projectId, mode, expectedRevision, idempotencyKey, factId; confirmed=true zum Anwenden.
reorder_business_offersSchreiben · mcp:editorial:writeDie Reihenfolge der Angebote in der Vorschau prüfen und dann ersetzen. Das Anwenden erfordert mcp:editorial:write.
Parameter: projectId, mode, expectedRevision, idempotencyKey, offerIds[]; confirmed=true zum Anwenden.
adopt_business_profileSchreiben · mcp:editorial:writeNur im Legacy-Modus: Das aus vorhandenen Daten wiederhergestellte Profil in der Vorschau prüfen und dann bestätigen, dabei falsche Fakten ablehnen und fehlende Kernfelder in derselben Änderung angeben. Kann nicht rückgängig gemacht werden. Das Anwenden erfordert mcp:editorial:write.
Parameter: projectId, mode, expectedRevision, idempotencyKey, rejectFactIds[], missingFacts[]{address, value}; confirmed=true zum Anwenden.
retry_project_contextSchreiben · mcp:editorial:writeDen Neuaufbau des Projektkontexts nach einem Fehlschlag neu starten (projectContext.retry = available in get_article_generation_readiness), wie über die Schaltfläche in den Einstellungen. Den Status in der Vorschau prüfen und dann erneut einreihen; ein wiederholter Aufruf gibt den bereits eingereihten Neuaufbau zurück; nach einem erneuten Fehlschlag ist jedes Anwenden ein neuer Versuch. Das Anwenden erfordert mcp:editorial:write.
Parameter: projectId, mode; confirmed=true zum Anwenden.
get_cms_configCMS-Typ, Verbindungsstatus, Datum des letzten Tests und nicht geheime Einstellungen lesen. Geheimnisse werden nie zurückgegeben, nur ob sie jeweils gespeichert sind.
Parameter: projectId.
configure_cmsSchreiben · mcp:integrations:writeDie nicht geheimen Einstellungen einer bestehenden WordPress-, Webflow-, Wix-, Framer- (sofern aktiviert) oder benutzerdefinierten Webhook-Verbindung in der Vorschau prüfen, dann speichern und testen. Zugangsdaten werden nur im PushRank-Dashboard eingegeben und bleiben unverändert. Shopify bleibt im Dashboard. Das Anwenden erfordert mcp:integrations:write und die Rolle Inhaber.
Parameter: projectId, mode, cmsType; je nach Typ: wpUrl, wpUsername | webflowCollectionId | wixSiteId, wixMemberId | framerProjectId, framerCollectionId, framerFieldMapping (Framer, sofern aktiviert) | webhookUrl; confirmed=true und idempotencyKey zum Anwenden.
get_publishing_scheduleDie in der Themen-Karte festgelegte Artikelplanung lesen: an/aus, Tage, Uhrzeit, Zeitzone und „Ohne Prüfung veröffentlichen“, den nächsten geplanten Artikel und was das Artikelkontingent bis zur Erneuerung erlaubt.
Parameter: projectId.
update_publishing_scheduleSchreiben · mcp:articles:generate, mcp:articles:publishEine Änderung der Artikelplanung in der Vorschau prüfen und dann anwenden, nach denselben Regeln wie in der Themen-Karte. Das Anwenden erfordert mcp:articles:generate, um an/aus, Tage, Uhrzeit oder Zeitzone zu ändern, und mcp:articles:publish, um „Ohne Prüfung veröffentlichen“ zu ändern.
Parameter: projectId, mode; optional enabled, publishDays (0 bis 7 Tage aus mon…sun), publishHour (0–23), timezone (Europe/Paris, Europe/London, America/New_York, America/Los_Angeles, Asia/Tokyo), autoPublish; confirmed=true und idempotencyKey zum Anwenden.
update_article_statusSchreiben · mcp:actions:writeDen gespeicherten Veröffentlichungsstatus eines Artikels zurückschreiben und die MCP-Herkunft erfassen. Erfordert den Scope mcp:actions:write.
Parameter: projectId, articleId, status (draft | published); optional: cmsUrl (nur HTTPS), publishedAt (ISO 8601, nur bei published; Standard ist jetzt). Planung wird nicht unterstützt, da dieses Tool keinen Planungszeitstempel hat.
schedule_article_publicationSchreiben · mcp:actions:writeEine künftige Artikelveröffentlichung mit der bestehenden Qualitätsprüfung und dem Schutz vor gleichzeitigen Zugriffen planen. Erfordert den Scope mcp:actions:write.
Parameter: projectId, articleId, scheduledAt (künftiger ISO-8601-Zeitstempel mit explizitem Offset).
cancel_article_publication_scheduleSchreiben · mcp:actions:writeEine ausstehende geplante Artikelveröffentlichung abbrechen. Wird abgelehnt, sobald der Veröffentlichungs-Worker sie übernommen hat. Erfordert den Scope mcp:actions:write.
Parameter: projectId, articleId.
list_keywordsAngereicherte Keywords mit Metriken, Status, Priorität, Artikelabdeckung und kanonischer Suchintention auflisten.
Parameter: projectId; optional: intent, source, status, search, limit (max. 25), offset (Paginierung über pagination.nextOffset).
get_keyword_metricsBereits gespeicherte Metriken für bis zu 20 Begriffe zurückgeben; ruft nie einen Anbieter auf und löst keine Aktualisierung aus.
Parameter: projectId, terms (1–20); optional: locale (Standard fr), locationCode (Standard 2250).
get_onboarding_checklistDie fünf Einstiegsschritte eines Projekts anzeigen, was noch zu tun ist, den Dashboard-Link für jeden Schritt und den Status des Willkommens-Backlinks. Clients mit Unterstützung für MCP Apps zeigen dies als interaktive Checkliste an.
Parameter: projectId.
claim_welcome_giftSchreiben · mcp:backlinks:writeDen nach Abschluss der fünf Schritte angebotenen Backlink in der Vorschau prüfen und dann anfordern: eine Seite der Website des Projekts und ihr Ankertext. Nur für Inhaber, mit Testphase oder aktivem Tarif; einer pro Organisation. Während der Testphase wird der Backlink nur reserviert: Er wird am Ende der Testphase mit dem ersten bezahlten Monat bestellt. Das Anwenden erfordert mcp:backlinks:write.
Parameter: projectId, mode, targetUrl, anchorText; confirmed=true zum Anwenden.
get_ai_visibilityLiest die KI-Sichtbarkeit eines Projekts: verfolgte Prompts, Score, Ergebnisse je Prompt und je KI-Engine (zitiert, erwähnt, Rang, Auszug), Messzeiträume und optional der Wettbewerbervergleich. Gibt nie den vollständigen Antworttext zurück und löst keine Messung aus.
Parameter: projectId; optional: collectionId, prompt, provider, offset, limit (1–25, Standard 15), includeCompetitors.
manage_ai_visibility_promptsSchreiben · mcp:ai-visibility:writeZeigt das Hinzufügen, Entfernen oder Umformulieren verfolgter Prompts in der Vorschau und wendet es dann an. Ein umformulierter Prompt beginnt ohne Verlauf. Löst keine Messung aus: neue Prompts werden bei der nächsten Messung erfasst. Anwenden erfordert mcp:ai-visibility:write.
Parameter: projectId, mode, operation (add mit prompts, remove mit prompts oder rename mit from und to); confirmed=true zum Anwenden.
OAuth-Verbindung
MCP-Clients wie Claude oder ChatGPT verbinden sich per OAuth: Geben Sie ihnen den Endpunkt, den Rest entdecken sie über die folgenden Metadaten.
https://ai.pushrank.io/.well-known/oauth-protected-resource/mcphttps://app.pushrank.io/.well-known/oauth-authorization-server- Erkennung — ein nicht authentifizierter Aufruf des Endpunkts liefert 401 mit einem WWW-Authenticate-Header, der auf die Ressourcen-Metadaten verweist; diese nennen den Autorisierungsserver und die unterstützten Scopes.
- Registrierung — der Client registriert sich per dynamischer Client-Registrierung (registration_endpoint) als öffentlicher Client, ohne Secret.
- Autorisierung — Authorization-Code-Flow mit PKCE (S256) und dem Parameter resource gleich dem MCP-Endpunkt; der Nutzer meldet sich bei Pushrank an und bestätigt die angeforderten Scopes.
- Tokens — der token_endpoint liefert ein Zugriffstoken mit 1 h Gültigkeit und, wenn offline_access angefordert wird, ein Refresh-Token mit 30 Tagen. Senden Sie das Zugriffstoken als Authorization: Bearer.
Manuelle API-Nutzung
Rufen Sie für ein Skript oder einen Client ohne OAuth den JSON-RPC-2.0-Endpunkt mit einem Bearer-Token auf, das im Tab „API / manuell“ erstellt wurde.
https://ai.pushrank.io/mcpErforderliche Header
- Authorization: Bearer <token> — bei jeder Anfrage erforderlich.
- Content-Type: application/json.
- Accept: application/json, text/event-stream.
- mcp-session-id — wird in den Antwort-Headern von initialize zurückgegeben; bei jedem weiteren Aufruf mitsenden.
- mcp-protocol-version: 2025-06-18 bei den Aufrufen nach initialize.
Aufrufreihenfolge
1. initialize — öffnet eine Sitzung. Lesen Sie den Antwort-Header mcp-session-id aus (curl -i).
curl -i -X POST "https://ai.pushrank.io/mcp" \
-H "Authorization: Bearer pushrank_mcp_xxxxxxxx" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"pushrank-manual-client","version":"1.0"}}}'2. tools/list — listet die verfügbaren Tools und ihre Eingabeschemas auf.
curl -X POST "https://ai.pushrank.io/mcp" \
-H "Authorization: Bearer pushrank_mcp_xxxxxxxx" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "mcp-session-id: <session-id>" \
-H "mcp-protocol-version: 2025-06-18" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'3. tools/call — führt ein Tool mit seinen Argumenten aus.
curl -X POST "https://ai.pushrank.io/mcp" \
-H "Authorization: Bearer pushrank_mcp_xxxxxxxx" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "mcp-session-id: <session-id>" \
-H "mcp-protocol-version: 2025-06-18" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_projects","arguments":{"limit":10}}}'Scopes, Limits und Widerruf
MCP-Tokens sind eigenständig und unabhängig von Ihrer Sitzung.
Manuelles Token
Ein manuelles Token hat standardmäßig die Scopes mcp:projects:read und mcp:actions:read. Es läuft nie ab und kann jederzeit widerrufen werden.
Schreibaktionen
Status- und Planungsänderungen erfordern mcp:actions:write. Die Generierung nutzt mcp:articles:generate, die Veröffentlichung mcp:articles:publish, die Artikelbearbeitung mcp:articles:write, Keyword-Änderungen mcp:keywords:write, die erneute Analyse mcp:analysis:run, der redaktionelle Kontext mcp:editorial:write, Änderungen der CMS-Verbindung mcp:integrations:write, die Anforderung des Willkommens-Backlinks mcp:backlinks:write und die verfolgten Prompts der KI-Sichtbarkeit mcp:ai-visibility:write. Änderungen der Artikelplanung nutzen mcp:articles:generate, „Ohne Prüfung veröffentlichen“ mcp:articles:publish. Diese eigenen Scopes werden über OAuth gewährt oder bei einem manuellen Schlüssel angehakt, bei der Erstellung oder später. Ein Token ohne den erforderlichen Scope erhält insufficientScope.
OAuth-Gültigkeitsdauer
Für OAuth-Clients (Claude, ChatGPT…) gilt das Access-Token 1 h und das Refresh-Token 30 Tage.
Widerruf
Widerrufen Sie ein manuelles Token im Tab „API / manuell“. Der Widerruf wirkt sofort und betrifft Ihre Sitzung nicht; OAuth-Zugriff wird im verbundenen Client widerrufen.
Organisationsbereich
Der Server beschränkt jede Antwort auf die Projekte der Organisationen, denen Sie angehören.