Tool-Referenz

list_scheduled_posts

Listet deine geplanten Beiträge auf (zur Veröffentlichung vorgemerkt, aber noch nicht gesendet).

Argumente

Rü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 deine Entwürfe auf (noch nicht geplant).

Argumente

Rü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 mit deinem Team verbundenen Social-Accounts auf.

Argumente

Keine Argumente.

Rückgabewert

Ein Objekt mit accounts: [{platform, handle, connected, lastSyncAt}].

Beispiel

{"jsonrpc":"2.0","method":"tools/call","id":3,
 "params":{"name":"list_connected_accounts","arguments":{}}}

get_account_healthBezahlpaket

Ruft eine Gesundheitszusammenfassung über alle verbundenen Plattformen ab.

Argumente

Rü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

Rü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

Aktualisiert einen bestehenden Entwurf. Mindestens eines von content oder mediaUrls muss angegeben werden.

Argumente

Rü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

Rü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 zukünftigen Zeitpunkt in die BullMQ-Veröffentlichungs-Queue. Idempotent innerhalb von ±60s Drift; lehnt Re-Scheduling-Versuche zu anderer Zeit ohne explizites Cancel ab.

Argumente

Rü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

Storniert einen geplanten Beitrag und entfernt ihn aus der Queue. Der zugrundeliegende Entwurf bleibt erhalten.

Argumente

Rü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 Nicht-DRAFT-Beiträge ab (für SCHEDULED nutze cancel_scheduled_post).

Argumente

Rü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

Rü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

Substring-Suche (case-insensitive) über Beitragsinhalte des aktiven Teams. Filter: status, platform, limit (1-100, Standard 20).

Argumente

Rü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 diesen Bearer-Token. Der Nutzer muss Mitglied sein. Persistent auf dem OAuth-Token-Dokument; In-Session-Mutation macht es sofort für nachfolgende Tools im selben Gespräch wirksam.

Argumente

Rü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 den aktuellen Subscription-Tier des Nutzers und die Quotas pro Tier (Kanäle, Speicher, KI-Credits, Posten). Auf jedem Plan verfügbar. Nützlich vor mutierenden Tools, um vorherzusagen, ob der Aufruf blockiert wird.

Argumente

Keine Argumente.

Rückgabewert

Ein Objekt mit tier, tierDisplayName, isPaid, isTrial, upgradeUrl, limits (channels/storage/aiCalls/posts jeweils als {limit, current, exceeded} oder {limit, allowed}) 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-Metriken für einen veröffentlichten Beitrag über alle Plattformen, auf denen er erschienen ist. Twitter und Instagram liefern populierte Metriken (Likes, Retweets/Shares, Kommentare/Antworten, Impressions); LinkedIn, Threads und TikTok liefern nur Veröffentlichungsstatus und URL (Engagement-Erfassung folgt in einem späteren Release). Eine normalisierte totals-Zusammenfassung addiert Likes/Kommentare/Shares/Impressions ü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 einen geplanten Beitrag: Queue-Status, Erfolg/Fehler pro Plattform, Verarbeitungszeit und Worker-Job-ID. Gibt isScheduled=false zurück für Beiträge, die als Entwurf existieren, aber nicht in die Veröffentlichungsqueue 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

Aktualisiert das aktive Markenprofil des Nutzers. Erlaubte Felder: bio, brandVoice, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize. Alles andere wird stillschweigend verworfen. "Aktiv" wird zuerst als Team-Default aufgelöst, dann das erste eigene aktive Profil des Nutzers.

Argumente

brandVoice Array von Markenstimme-Deskriptoren (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 Plan

Empfiehlt die besten N (Wochentag, Stunde) Slots für den nächsten Beitrag auf einer Plattform, sortiert nach Engagement pro Beitrag der letzten 90 Tage. Twitter und Instagram liefern engagement-gewichtete Scores; LinkedIn, Threads, TikTok sortieren nur nach Beitragshäufigkeit. Zeiten in der angegebenen IANA-Zeitzone (Standard UTC). Bezahlplan 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, Mo=1), dayLabel, hour (0-23), score, basedOn: {posts, avgEngagement}}]. Enthält hint für Cold-Start- oder Metriken-fehlen-Fälle.

Beispiel

{"jsonrpc":"2.0","method":"tools/call","id":19,
 "params":{"name":"get_best_time_to_post",
           "arguments":{"platform":"twitter","timezone":"Europe/Berlin","topN":5}}}

search_tools

Durchsucht den MCP-Tool-Katalog nach Freitext, Kategorie oder Absicht. Liefert Kategorien, requiresScope, einzeilige Beschreibungen und passende Use-Case-Tags. Auf jedem Plan verfügbar (Discovery-Oberfläche).

Argumente

All optional. Call with no arguments to list every available tool.

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"}}}