posterly

Add a photo or video to a Google Business Profile gallery (the media shown on Maps and Search). Provide a public https source_url first by uploading via upload_media_from_url or upload_media. COVER and PROFILE are single-slot and replace the existing one. WRITE: show the location, category, and media URL to the user, then pass confirm=true only after explicit confirmation.

Ask Posterly Support AI an authenticated question using Posterly docs plus read-only account/post diagnostics for the caller workspace. Requires POSTERLY_API_KEY with accounts:read and posts:read scopes. Human ticket creation requires request_human=true and confirm_escalation=true after explicit user confirmation.

Run a live local-profile audit for a connected Google Business Profile location, including completeness, categories, media, attributes, reviews, and recommendations.

Cancel the authenticated user's posterly subscription. DESTRUCTIVE billing action; requires the billing:write scope. ALWAYS ask the user why they are cancelling FIRST and pass their answer as `reason` (one of the allowed values). By default the subscription is set to cancel at the end of the current period; pass immediate=true only if the user explicitly wants it cancelled right now. Only call after the user explicitly confirms.

Create a new Posterly API key for the authenticated user. SECRET-CREATING WRITE: only use after explicit user confirmation. The new key can only request scopes already present on the calling dashboard-created API key; OAuth and managed assistant tokens cannot mint keys.

Create a short-lived Posterly dashboard handoff session for connecting a social account. Send the secure connection URL to the user, then poll get_connect_session to narrate progress. Do not ask for social media passwords or OAuth codes; Posterly handles those browser steps.

Create a public OAuth 2.1 + PKCE developer client. WRITE: confirm app name, redirect URIs, and scopes with the user before calling.

Schedule or immediately publish a social media post. This is a DESTRUCTIVE WRITE that creates content on the user's real social accounts - once scheduled_at passes, it will be posted publicly and cannot be un-posted. REQUIRED BEFORE CALLING: 1. Call `whoami` at the start of any new session to confirm which workspace and user you are acting for. 2. Show the user a preview containing ALL of: account(s) and platform(s), final caption text, scheduled time (in the user's timezone), media attached (if any), and workspace name. 3. Get explicit confirmation from the user (e.g. "post it", "yes schedule that", "looks good") BEFORE calling this tool. Do NOT infer consent from earlier instructions like "post about X every Monday" - confirm each individual post or the entire batch. 4. If scheduling multiple posts in one turn, list every post first and confirm the batch as a whole, then prefer `create_posts_batch` so they are created in one API request. AFTER CALLING: Tell the user the post was created, include the Posterly dashboard link returned by the tool, and offer the next natural action. Do not narrate raw HTTP, curl, or API plumbing. Provide either account_id OR username+platform to identify the account. If scheduled_at is omitted, the post publishes immediately. If workspace_id is omitted, the server resolves one from the social account, falling back to the caller's default (personal) workspace - pass workspace_id explicitly if the user has more than one workspace. MEDIA URLS: Posterly storage URLs are used as-is. Third-party HTTP(S) media URLs are copied into Posterly storage before the post is saved, so API-created posts do not later fail on expired signed URLs. Short-lived signed URLs must still be live when this tool runs. You can also call `upload_media_from_url` first if you want to upload once and reuse the returned Posterly URL across posts. THREADS: Pass `thread_posts` (an array of 2+ strings) to schedule a multi-post thread on X (Twitter) or Threads (Meta…

Create 1-25 scheduled or immediate social posts in one API request. This is a DESTRUCTIVE WRITE that creates content on the user's real social accounts - once scheduled_at passes, posts may go public and cannot be un-posted. REQUIRED BEFORE CALLING: 1. Call `whoami` at the start of any new session to confirm which workspace and user you are acting for. 2. Show the user a preview of EVERY post: account/platform, final caption or thread text, scheduled time in their timezone, media, platform settings, and workspace. 3. Get explicit confirmation for the whole batch before calling. Do not infer consent from an earlier content plan. AFTER CALLING: Summarize the batch result in natural language, include the Posterly dashboard link returned by the tool, and avoid narrating raw HTTP, curl, or API plumbing. Each item accepts the same fields as `create_post`, including `thread_posts`, `platform_settings`, `instagram_settings`, media URLs, and workspace_id. The endpoint may partially succeed; failed items are returned with their index.

Create a signed upload URL for a larger image or video. Upload the binary to upload_url; the API validates actual bytes before storage, then public_url can be used with create_post.

Create a webhook subscription for post/account/analytics events. WRITE WITH OUTBOUND SIDE EFFECTS: show the user the target URL, workspace, events, and active state, then get explicit confirmation before calling. The response includes the signing secret once.

Revoke a Posterly API key owned by the authenticated user. DESTRUCTIVE: call whoami or use a known key ID, show the user the exact key ID/prefix/name if available, and get explicit confirmation before calling. Cannot revoke the key currently authenticating this request, OAuth-issued keys, or managed assistant keys.

Remove a photo or video from a Google Business Profile gallery. Get media_name from list_google_business_media. This permanently deletes the item from the public profile. WRITE: show the exact media item and location to the user, then pass confirm=true only after explicit confirmation.

Delete the owner reply from a Google Business Profile review. DESTRUCTIVE: confirm the review and location with the user, then pass confirm=true only after explicit confirmation.

Delete a self-serve OAuth developer client. DESTRUCTIVE: prevents new authorizations for that client_id; existing access tokens remain revocable as API keys.

Delete a scheduled or draft post. DESTRUCTIVE and IRREVERSIBLE - the post and its caption cannot be recovered. Cannot delete published or currently publishing posts. REQUIRED BEFORE CALLING: Fetch the post with `get_post` first and show the user what will be deleted (caption, account, scheduled time). Get explicit confirmation ("yes delete it", "remove it") before calling. Never delete multiple posts in a single batch without listing each one and confirming the full list.

Delete every draft/scheduled/failed/paused post matching a caller-defined group_id, post_group_id, api_group_id, or release_id. DESTRUCTIVE: inspect the group first, list the affected posts, and pass confirm=true only after explicit confirmation.

Delete a webhook subscription. DESTRUCTIVE: list the webhook first, show the user its URL/events/workspace, and get explicit confirmation before calling.

Disconnect a connected social account from posterly. DESTRUCTIVE and IRREVERSIBLE: removes the account connection, emits account.disconnected webhooks, and may transfer Instagram scheduled posts to a replacement account. REQUIRED BEFORE CALLING: Call `list_accounts` first, show the user the exact platform, username, account ID, and workspace that will be disconnected, then get explicit confirmation. Pass confirm=true only after that confirmation.

Dismiss a proactive post suggestion so it stops appearing. WRITE: confirm the exact suggestion with the user first. Never dismisses a suggestion that was already turned into a scheduled post (that would break adoption tracking).

Downgrade the authenticated user's posterly subscription one tier (or to an explicit lower `tier`) at the next renewal with no proration. Billing action; requires the billing:write scope. Only call after the user explicitly confirms.

Find available time slots for posting. Respects a 1-hour gap between posts and preferred hours (8am-10pm in the given timezone). Returns up to 10 slots. IMPORTANT: pass a timezone explicitly - default is America/New_York and slots will be off if the user is elsewhere. Pass workspace_id to only avoid collisions with posts in that workspace.

Generate or adapt AI caption suggestions for one or more social platforms. Uses AI Caption Assist quota and returns options only; it does not create or schedule posts. After the user chooses final copy, pass it to create_post or create_posts_batch.

Generate an AI image via Posterly's Nano Banana (Gemini) integration. The image is saved to the user's media storage and the returned URL can be passed to `create_post` as `media_url`. COSTS CREDITS. Every call consumes part of the user's monthly AI image quota (or purchased credits once the quota is exhausted). Do NOT call speculatively - always describe the image you're about to generate (subject, style, aspect ratio) to the user and get confirmation before calling. If the user is over their plan limit and has no credits, this tool returns a 402 with upgrade info. Surface that message verbatim - do not retry. Common aspect ratios by platform: • Instagram feed / LinkedIn: 1:1 (square) or 4:5 (portrait) • Instagram Story/Reel, TikTok, YouTube Shorts: 9:16 • YouTube thumbnail, Twitter cards, landscape feed: 16:9 • Pinterest: 2:3

Queue a Veo AI video generation job. COSTS VEO CREDITS: confirm prompt, model, duration, resolution, aspect ratio, audio choice, and credit cost with the user before calling. Poll get_video_job for status and final video_url.

Get daily analytics snapshots and a period summary for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, YouTube, and Threads. Uses API-provided display_metrics for platform-native dashboard labels and supports presentation: compact, table, or json.

Explain how to use Posterly MCP for agent-led signup before an API key exists, including the safe human-in-the-browser boundaries.

Get one brand/client by ID. Returns its workspace, source, linked legacy brand group if present, and the number of social accounts assigned to it.

Get the extended brand profile for a brand/client. Returns voice/tone guidance, audience, keywords, dos and don’ts, visual notes, and other saved brand context.

List dashboard handoff links/readiness for connecting social accounts, or get one platform connection URL. Use connection_url in a logged-in browser. Direct OAuth URLs are intentionally not exposed because provider callbacks rely on browser state.

Poll a Posterly connect session. Use the returned status and next-step guidance to keep the user updated in plain language. Stop when status is connected, failed, cancelled, or expired.

Get the direct public Google review link for a connected Google Business Profile location. Requires account_id or location_id. Returns reviewLink plus the Google Place ID (ChIJ...); that Place ID is output only and must NOT be passed back as location_id to other tools.

Get the voice posterly has learned from a connected account’s real published captions (the "learned captions" shown on the dashboard). Returns a narrative summary, voice traits, style guidelines, and observed posting habits. Keyed by social account ID (from list_accounts or list_brand_accounts). Returns nothing until the account has enough published posts to learn from. Read-only; this never overwrites the saved brand profile.

Report the Posterly MCP server version, latest npm version, MCP endpoint health, API key health, and update guidance. Safe to call before POSTERLY_API_KEY is configured.

Get the performance profile posterly has derived for a connected account from the last 90 days of per-post analytics. Returns coaching stats (format, timing, caption-length patterns), an engagement-rate trend, and a narrative summary. Keyed by social account ID (from list_accounts or list_brand_accounts). Returns nothing until the account has a derived profile; Google Business Profile and other platforms without per-post analytics never get one. Read-only; requires a Pro plan or higher.

Get the platform schema for a specific connected account or platform. Call this before creating posts with platform_settings so you know allowed post types, media limits, helper tools, and field names.

Get details of a specific post by ID. Returns caption, status, scheduled time, media, and platform info.

Get per-post engagement metrics (likes, comments/replies, reach, impressions/views, saves, shares, reposts, quotes, plays, clicks, watch time) for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, YouTube, and Threads. Returns the most recent posts first. presentation controls output: compact for Telegram/mobile, table for Markdown clients, json for custom chart/card renderers.

List per-post feedback insights from the posterly performance feedback loop: for recently published posts, the performance tier (great/good/mixed/poor), a diagnosis, a suggested next action, metrics, and the baseline it was compared against. Filter by account_id, post_id, and checkpoint (1h, 6h, 24h, 72h, 7d). Read-only; requires a Pro plan or higher.

Inspect whether a post is missing required content, media, account, platform settings, or metadata before it can publish. Use this to repair failed or imported posts.

Poll a public Posterly signup session created by start_signup. Use this to narrate checkout, payment, password setup, and agent access status before a Posterly API key is installed. Keep updates user-facing; do not narrate raw HTTP, curl, or API plumbing.

Get the authenticated user's posterly subscription: status, tier, cancel-at-period-end, current period end, trial end, and pause state. Read-only. Requires the billing:read scope.

Get the latest posterly product updates and news from the updates feed: new features, improvements, and fixes. Requires an active posterly subscription.

Get one Veo video generation job by ID, or list recent video jobs when job_id is omitted. Use after generate_video to poll for completed video_url.

List read-only Veo video generation options, input modes, durations, resolutions, aspect ratios, and credit-cost estimates. This does not generate video or spend credits.

Get managed X posting quota for a workspace, including total monthly allowance, used posts, remaining posts, and URL-blocking status.

List connected social media accounts. Returns platform, username, account ID, and workspace ID for each. Pass workspace_id to filter to a specific workspace; otherwise returns all accounts the caller owns across every workspace.

List recent activity and publish events for posts, including status changes, publish attempts, failures, and retries. Use this as the agent notifications feed.

List the connected social accounts assigned to a brand/client. Use this when a user refers to a brand name rather than a raw account handle.

List brands/clients the caller can access. Returns each brand ID, name, workspace ID, source, and how many social accounts are currently assigned to it.