MCP-Tool-Referenz für Social Media
Jedes Tool, das der PostNext-MCP-Server bereitstellt, mit seinen Eingaben, der Rückgabestruktur und einem Beispiel zum Kopieren.
https://mcp.postnext.io/apiPOST https://mcp.postnext.io/apiAuthentifizierung
Jede Anfrage an https://mcp.postnext.io/api braucht einen Authorization-Header mit einem Bearer-Token. Dafür gibt es zwei Wege.
OAuth (empfohlen für KI-Clients)
KI-Clients führen beim ersten Verbinden eine Dynamic Client Registration durch und führen den Nutzer dann durch eine OAuth-Zustimmungsseite. Die Seite /mcp/connect erledigt das automatisch. Ihr Client erhält ein Zugriffstoken für 30 Tage.
API-Schlüssel
Für Skripte und CI erstellen Sie in der PostNext-App unter Konto → API-Schlüssel einen persönlichen API-Schlüssel. Er beginnt mit apikey_ und wird wie jedes andere Bearer-Token übergeben.
Endpoint
Alle Tool-Aufrufe gehen an einen einzigen JSON-RPC-2.0-Endpoint per HTTPS POST.
Tools
list_scheduled_posts
Listet Ihre geplanten Beiträge auf (zur Veröffentlichung eingeplant, aber noch nicht gesendet).
Argumente
limitfromRückgabewert
Ein Objekt mit posts: [{id, platform, content, scheduledAt, status}]. Bis zu limit Einträge.
Beispiel
curl -X POST https://mcp.postnext.io/api \
-H "Authorization: Bearer apikey_xxx" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/call","id":1,
"params":{"name":"list_scheduled_posts",
"arguments":{"limit":5}}}'
list_drafts
Listet Ihre Entwürfe auf (noch nicht geplant).
Argumente
limitRückgabewert
Ein Objekt mit drafts: [{id, platform, content, updatedAt}]. Bis zu limit Einträge.
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":2,
"params":{"name":"list_drafts","arguments":{"limit":10}}}
list_connected_accounts
Listet die Social-Konten auf, die mit Ihrem Team verbunden sind.
Argumente
Keine Argumente.
Rückgabewert
Ein Objekt mit accounts: [{platform, handle, providerId, connected, lastSyncAt}].
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":3,
"params":{"name":"list_connected_accounts","arguments":{}}}
get_account_healthBezahlter Tarif
Ruft eine Übersicht zum Kontostatus über alle verbundenen Plattformen ab.
Argumente
platformwindowDaysRückgabewert
Ein Objekt mit windowDays, postsScheduled, postsPublished, postsFailed, einer byPlatform-Aufschlüsselung und topErrors[].
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":4,
"params":{"name":"get_account_health",
"arguments":{"windowDays":30}}}
create_post_draft
Erstellt einen neuen Entwurf. Entwürfe werden nicht automatisch veröffentlicht.
Argumente
platformcontentchannelNameproviderIdmediaUrlsclientRequestIdRückgabewert
Ein Objekt mit dem neuen Entwurf: {id, platform, content, status: "DRAFT", createdAt}.
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":5,
"params":{"name":"create_post_draft",
"arguments":{"platform":"twitter",
"content":"Hello from MCP"}}}
update_post_draft Bezahlter Tarif
Aktualisiert einen bestehenden Entwurf. Mindestens eines von content oder mediaUrls muss angegeben werden.
Argumente
postIdcontentmediaUrlsclientRequestIdRückgabewert
Ein Objekt mit dem aktualisierten Entwurf: {id, platform, content, mediaUrls, status, updatedAt}.
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":6,
"params":{"name":"update_post_draft",
"arguments":{"postId":"",
"content":"Updated copy"}}}
connect_channel
Generiert eine Einmal-URL, die der Nutzer öffnen kann, um eine neue Plattformverbindung zu autorisieren.
Argumente
platformRückgabewert
Ein Objekt mit authUrl (einmaliger Link, den der Nutzer zur Autorisierung öffnet), expiresAt und platform.
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":7,
"params":{"name":"connect_channel",
"arguments":{"platform":"linkedin"}}}
schedule_post
Verschiebt einen Entwurf (Status DRAFT) zu einem späteren Zeitpunkt in die Warteschlange zur Veröffentlichung. Idempotent bei bis zu ±60 s Abweichung. Ein erneutes Einplanen zu einer anderen Zeit wird abgelehnt, solange der Beitrag nicht zuerst abgebrochen wurde. Zählt zu den monatlichen Beiträgen des Tarifs (kostenloser Tarif: 10, gemeinsam mit der App). Ein Beitrag zählt einmal: Erneutes Einplanen nach einem Abbruch oder einer fehlgeschlagenen Veröffentlichung zählt nicht noch einmal.
Argumente
postIdscheduledAtRückgabewert
Ein Objekt mit postId, scheduledAt (ISO), status: SCHEDULED.
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":8,
"params":{"name":"schedule_post",
"arguments":{"postId":"",
"scheduledAt":"2026-05-10T09:00:00Z"}}}
cancel_scheduled_post
Bricht einen geplanten Beitrag ab und entfernt ihn aus der Warteschlange. Der zugrunde liegende Entwurf bleibt erhalten.
Argumente
postIdRückgabewert
Ein Objekt mit postId und status: CANCELLED.
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":9,
"params":{"name":"cancel_scheduled_post",
"arguments":{"postId":""}}}
delete_draft
Löscht einen Entwurf dauerhaft. Lehnt Beiträge ab, die nicht DRAFT sind (für SCHEDULED verwenden Sie cancel_scheduled_post).
Argumente
postIdRückgabewert
Ein Objekt mit postId und deleted: true.
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":10,
"params":{"name":"delete_draft",
"arguments":{"postId":""}}}
get_post
Liefert die vollständige PostGroup für eine postId mit Provider-Inhalten je Plattform + Status + Zeitstempeln.
Argumente
postIdRückgabewert
Ein Objekt mit postId, status, scheduledAt, createdAt, updatedAt und providers (Map: Plattform → Inhalt).
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":11,
"params":{"name":"get_post",
"arguments":{"postId":""}}}
search_posts
Teilstring-Suche (ohne Unterscheidung von Groß- und Kleinschreibung) in den Beitragsinhalten des aktiven Teams. Filter: status, platform, limit (1-100, Standard 20).
Argumente
querystatusplatformlimitRückgabewert
Ein Objekt mit posts: [{postId, status, platforms, snippet, scheduledAt, updatedAt}]. Snippet enthält den passenden Kontext mit Auslassungspunkten beidseitig.
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":12,
"params":{"name":"search_posts",
"arguments":{"query":"launch","limit":10}}}
list_teams
Gibt die Teams zurück, deren Eigentümer oder Admin der angemeldete Nutzer ist, mit Markierung des aktiven Teams.
Argumente
Keine Argumente.
Rückgabewert
Ein Objekt mit currentTeamId und teams: [{teamId, teamName, isCurrent}].
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":13,
"params":{"name":"list_teams","arguments":{}}}
set_current_team
Wechselt das aktive Team für dieses Bearer-Token. Der Nutzer muss Mitglied sein. Die Auswahl wird im OAuth-Token-Dokument gespeichert und gilt sofort für alle folgenden Tools im selben Gespräch.
Argumente
teamIdRückgabewert
Ein Objekt mit teamId, teamName, persisted (true bei OAuth, false bei API-Key) und optionalem note.
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":14,
"params":{"name":"set_current_team",
"arguments":{"teamId":"team_xxxxx"}}}
get_plan_limits
Liest die aktuelle Tarifstufe des Nutzers und die Kontingente pro Stufe (Kanäle, Speicher, KI-Credits, Veröffentlichungen). In jedem Tarif verfügbar. Nützlich vor Tools, die etwas ändern, um vorherzusagen, ob der Aufruf blockiert wird.
Argumente
Keine Argumente.
Rückgabewert
Ein Objekt mit tier, tierDisplayName, isPaid, isTrial, limits (channels/storage/aiCalls jeweils als {limit, current, exceeded}; posts als {limit, allowed, current}, wobei current die Zahl dieses Monats ist oder null, wenn sie nicht gelesen werden konnte) und creditsAvailable ({total, subscriptionRemaining, purchasedBalance} oder null).
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":15,
"params":{"name":"get_plan_limits","arguments":{}}}
get_post_metrics
Holt Engagement-Kennzahlen für einen veröffentlichten Beitrag über alle Plattformen, auf denen er erschienen ist. Twitter liefert Likes, Retweets, Antworten und Impressionen, Instagram liefert Likes und Kommentare. LinkedIn, Threads und TikTok liefern nur Veröffentlichungsstatus und URL (die Erfassung von Engagement folgt in einer späteren Version). Eine normalisierte totals-Summe addiert die Kennzahlen über alle Plattformen, die Werte gemeldet haben.
Argumente
postId PostNext-Post-ID aus einem Listenaufruf.
Rückgabewert
Ein Objekt mit postId, status, providers: [{platform, publishedPostId, publishedUrl, publishedAt, status, metrics}] und totals: {likes, comments, shares, impressions}. metrics ist ein Objekt mit numerischen Zählern pro Plattform oder null, wenn die Plattform noch keine Engagement-Daten erfasst.
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":16,
"params":{"name":"get_post_metrics",
"arguments":{"postId":""}}}
get_publish_status
Diagnostiziert, was mit einem geplanten Beitrag passiert ist: Status in der Warteschlange, Erfolg oder Fehler pro Plattform, Verarbeitungszeit und die Job-ID des Workers. Gibt isScheduled=false zurück für Beiträge, die als Entwurf existieren, aber nie in die Veröffentlichungswarteschlange verschoben wurden, mit einem Hinweis auf schedule_post.
Argumente
postId PostNext-Post-ID aus einem Listenaufruf.
Rückgabewert
Ein Objekt mit postId, isScheduled, status, scheduledAt, publishedAt, platforms, processingTimeMs, jobId, topLevelError und results: [{platform, success, publishedPostId, publishedAt, error}]. Enthält hint, wenn isScheduled false ist.
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":17,
"params":{"name":"get_publish_status",
"arguments":{"postId":""}}}
update_brand_profile Bezahlter Tarif
Aktualisiert das aktive Markenprofil des Nutzers. Erlaubte Felder: bio, brandVoice, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize. Alles andere wird stillschweigend verworfen. "Aktiv" ist zuerst der Team-Standard, danach das erste eigene aktive Profil des Nutzers.
Argumente
brandVoice Array mit Begriffen für die Markenstimme (z. B. ["professionell", "präzise"]).
Other patchable fields: bio, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize.
Rückgabewert
Ein Objekt mit profileId, name, updated: [Feldnamen, die gepatcht wurden] und den aktuellen Werten von bio, brandVoice, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize nach dem Patch.
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":18,
"params":{"name":"update_brand_profile",
"arguments":{"brandVoice":["professional","concise"]}}}
get_best_time_to_post Bezahlter Tarif
Empfiehlt die besten N Slots (Wochentag, Stunde) für den nächsten Beitrag auf einer Plattform, aus den letzten 90 Tagen. Twitter und Instagram werden nach Interaktionen pro Beitrag sortiert, LinkedIn, Threads und TikTok nur nach Posting-Häufigkeit. Zeiten in der angegebenen IANA-Zeitzone (Standard UTC). Bezahlter Tarif erforderlich.
Argumente
platform Social-Plattform: twitter, instagram, linkedin, threads oder tiktok.
timezone IANA-Zeitzonenname (z. B. Europe/Berlin, America/New_York). Standard UTC.
topN Anzahl der Slot-Empfehlungen (1-24, Standard 5).
Rückgabewert
Ein Objekt mit platform, timezone, sampleWindowDays, sampleSize, metricsAvailable und recommendations: [{dayOfWeek (1-7, Mon=1), dayLabel, hour (0-23), score, basedOn: {posts, avgEngagement}}]. Enthält hint bei Kaltstart oder fehlenden Kennzahlen.
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":19,
"params":{"name":"get_best_time_to_post",
"arguments":{"platform":"twitter","timezone":"Europe/Berlin","topN":5}}}
get_channel_analytics
Gesamtleistung eines verbundenen Kanals oder aller Kanäle auf einmal. Liefert Impressionen, Reichweite, Likes, Kommentare und Engagement-Rate für den Zeitraum, die Veränderung gegenüber dem gleich langen Zeitraum davor und die Follower-Entwicklung. Ohne platform kommt die Summe des ganzen Teams. Für einen einzelnen Beitrag get_post_metrics, für die Planung get_best_time_to_post.
Argumente
platform Social-Plattform: twitter, instagram, linkedin, threads oder tiktok.
channelName Welches verbundene Konto, wenn die Plattform mehr als eines hat.
providerId Die providerId des Kontos aus list_connected_accounts. Sie bleibt gleich, wenn sich das Handle ändert; übergeben Sie sie zusammen mit channelName oder stattdessen.
period Zeitraum: 7d, 30d, 90d oder all (Standard 30d).
Rückgabewert
Ein Objekt mit scope, period, totals, vsPrevious, coverage, dataThrough und followers, das trackingSince, current, change und die Zeitreihe enthält.
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":34,
"params":{"name":"get_channel_analytics",
"arguments":{"platform":"linkedin","period":"30d"}}}search_tools
Durchsucht den MCP-Tool-Katalog nach Freitext, Kategorie oder Absicht. Liefert Kategorien, requiresScope, einzeilige Beschreibungen und passende Use-Case-Tags. In jedem Tarif kostenlos (Funktion zum Entdecken).
Argumente
Alle optional. Ohne Argumente erhalten Sie eine Liste aller verfügbaren Tools.
query Freitextsuche über Tool-Namen, Beschreibungen und Use-Case-Tags.
category Auf eine Kategorie filtern: posts, accounts, analytics, brand, teams, discovery, other.
Rückgabewert
Ein Objekt mit totalTools, matchCount, categories: [string[]] und tools: [{name, category, requiresScope, description, useCases, matchedOn: [name|category|description|use_case]}]. Enthält hint bei keinem Treffer oder keinem Filter.
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":20,
"params":{"name":"search_tools",
"arguments":{"query":"why did my post fail"}}}
get_plan
Tarif und Abrechnungstermine: Stufe, Verlängerungsdatum, Testende und ob das Abo zum Periodenende gekündigt wird. Für Kontingente und Verbrauch stattdessen get_plan_limits aufrufen.
Argumente
Keine Argumente.
Rückgabewert
Ein Objekt mit tier, tierDisplayName, isPaid, isTrial, gated, subscriptionStatus, renewsAt, trialEndsAt, cancelAtPeriodEnd und currency.
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":21,
"params":{"name":"get_plan",
"arguments":{}}}
upload_asset
Bild- oder Video-Upload direkt als Base64 in die Mediathek. Nur für sehr kleine Dateien zuverlässig, etwa 8 KB oder weniger: größere Daten werden in den Tool-Argumenten stillschweigend abgeschnitten und als defekte Datei gespeichert. Für alles Größere request_asset_upload verwenden.
Argumente
filename Dateiname samt Endung, bis zu 255 Zeichen.
contentType MIME-Typ der Datei, aus der erlaubten Liste für Bilder und Videos.
base64 Die Dateibytes, base64-kodiert. Sehr klein halten und zuerst den Hinweis oben lesen.
Rückgabewert
Ein Objekt mit assetId, url, sizeBytes und mimeType. Die url als mediaUrls an create_post_draft übergeben.
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":22,
"params":{"name":"upload_asset",
"arguments":{"filename":"logo.png","contentType":"image/png","base64":"iVBORw0KGgo..."}}}
request_asset_upload
Der empfohlene Upload-Weg für Bilder und Videos jeder Größe. Zwei Schritte: dieses Tool aufrufen und eine vorsignierte URL samt fertigem curl-Befehl erhalten, dann die Datei per PUT an diese URL senden. Die Antwort auf das PUT enthält die endgültige Asset-URL.
Argumente
filename Dateiname samt Endung, bis zu 255 Zeichen.
contentType MIME-Typ der Datei, aus der erlaubten Liste für Bilder und Videos.
sizeBytes Genaue Dateigröße in Bytes, wird zum Signieren des Uploads verwendet.
Rückgabewert
Ein Objekt mit uploadId, uploadUrl, uploadToken, expiresInSeconds und instructions mit dem genauen PUT-Befehl.
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":23,
"params":{"name":"request_asset_upload",
"arguments":{"filename":"clip.mp4","contentType":"video/mp4","sizeBytes":4194304}}}
import_chat_file
Nur in ChatGPT. Speichert im Chat angehängte Bilder und Videos in Ihrer Mediathek, bereit für create_post_draft. ChatGPT übergibt jede Datei als temporären Link. PostNext lädt sie einmal über HTTPS herunter und prüft an der Datei selbst, ob es ein Bild oder Video ist. Bis zu 10 Dateien pro Aufruf, je 50 MB, angerechnet auf den Speicher Ihres Tarifs (im kostenlosen Tarif insgesamt 10 MB).
Argumente
files Von ChatGPT aus den im Chat angehängten Dateien befüllt: download_url und file_id, optional mime_type und file_name. Bis zu 10. Andere Clients laden mit request_asset_upload hoch.
Rückgabewert
Ein Objekt mit files (assetId, url, sizeBytes, mimeType und fileName je gespeicherter Datei) und failed (fileName und reason je Datei, die nicht gespeichert werden konnte). Konnte keine Datei gespeichert werden, liefert der Aufruf stattdessen den Fehler der ersten Datei.
Beispiel
{"jsonrpc":"2.0","method":"tools/call","id":35,
"params":{"name":"import_chat_file",
"arguments":{"files":[{"download_url":"https://files.oaiusercontent.com/...","file_id":"file_abc123"}]}}}
MCP-Ressourcen
Ressourcen sind nur lesbarer Kontext, den der Client über die MCP-Methode resources/read abruft. Claude lädt sie zu Beginn jedes Gesprächs und kennt so Konto, Team und Marke, ohne dass Sie das in jeder Sitzung neu erklären.
postnext://account/summary
Konto-E-Mail und Handle (damit Claude bestätigen kann, mit welchem Konto es arbeitet), Tarif, genutzte KI-Credits / Limit, Anzahl der Entwürfe, geplanten Beiträge und verbundenen Kanäle. Jede Zahl ist für schnelles Laden auf 100 begrenzt.
postnext://channels/connected
Gleiche Form wie das Ergebnis von list_connected_accounts; als Ressource bereitgestellt, sodass Claude es zu Gesprächsbeginn einmal lädt (ohne zusätzlichen Tool-Aufruf).
postnext://brand-profiles/active
Das aktive Markenprofil des Nutzers (Team-Standard, Fallback auf erstes eigenes Profil). Liefert nur LLM-relevante Felder: bio, expertiseAreas, personalityTraits, brandVoice, mainThemes, audienceSize, preferredHashtags.
postnext://teams/current
Metadaten des aktuellen Teams (teamId, teamName) plus totalTeamsAvailable. Zum Wechseln mit list_teams und set_current_team kombinieren.
Benannte Workflows
Kurzbefehle im Slash-Menü, die mehrere Tools verketten. Wählen Sie einen aus, und Ihr KI-Assistent arbeitet eine Aufgabe in mehreren Schritten ab. Vor jeder Änderung fragt er nach.
/weekly-plan
Liest Markenprofil, verbundene Kanäle und geplante Beiträge und schlägt 5 bis 10 Entwürfe von Montag bis Freitag vor.
/draft-thread
Schreibt einen Thread für X oder Threads aus 5 bis 10 Beiträgen zu einem Thema oder einer URL, in Ihrer Markenstimme.
/audit-queue
Prüft die geplanten Beiträge der nächsten 7 Tage und meldet Duplikate, Plattform-Überlastung und Lücken.
/channel-sweep
Vergleicht verbundene Kanäle mit der unterstützten Liste und schlägt vor, welche zu verbinden oder aufzufrischen sind.
Discovery- und OAuth-Endpoints
Standardkonforme Metadaten, damit jeder MCP-Client sich selbst konfigurieren kann.
GET /.well-known/oauth-protected-resource/api— RFC 9728GET /.well-known/oauth-authorization-server— RFC 8414GET /oauth/.well-known/openid-configuration— OIDCPOST /oauth/reg— Dynamic Client Registration (RFC 7591)GET /oauth/auth— Authorize (PKCE-S256 required)POST /oauth/token— Token exchange
Open Source
Rezepte zum direkten Einfügen und eine Referenz für Entwickler finden Sie in unserem öffentlichen Docs-Repo. MIT-lizenziert, Pull Requests sind willkommen. github.com/postnextio/postnext-mcp
Social-Media-MCP für Claude, ChatGPT und jeden KI-Agenten
Mit dem Social-Media-MCP-Server von PostNext planen Claude, ChatGPT und jeder KI-Agent Ihre Beiträge. Entwürfe warten im Kalender, bis Sie sie einplanen.