Skip to main content
Glama
Sign In
posterly-mcp-server

posterly-mcp-server

by awpthorp
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

create_post

Schedule or immediately publish social media posts to connected accounts with media, threads, and platform-specific settings after explicit user confirmation.

Instructions

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 with 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). The first entry is the lead post; the rest are published as replies in the same chain. X entries are capped at 280 characters each (4000 for verified, 25000 for organization accounts); Threads entries are capped at 500 characters each. When thread_posts is set, caption is ignored.

X ARTICLES: To publish on X as a long-form Article, pass platform_settings.article ({ title, cover?: "first_image" | "none" }) for an X account. The caption becomes the Article body and is written as Markdown (headings, bold, italic, lists, quotes, code blocks, tables, dividers). Reference attached images with ![caption](media:1). Needs an X Premium account; polls, threads, paid partnership, video, and GIFs are not allowed with an Article.

PLATFORM SETTINGS: Pass platform_settings for composer-equivalent controls: Facebook story/reel/backgrounds, YouTube title/privacy/thumbnail/brandPartner, LinkedIn document titles/mentions/polls/content_call_to_action_label (including BUY_NOW and SHOP_NOW), TikTok direct-post privacy/toggles/commercial disclosure, Pinterest board/title/link/product_tags, GBP event/offer/CTA/recurrence, X reply settings/polls/paid_partnership, Threads reply controls/text attachments/ghost posts/spoilers/reply approvals/GIPHY, Telegram polls/buttons/video cover/live photo, Slack markdown/blocks, Mastodon visibility/quote/poll (media+poll allowed), and Instagram feed/story/reel/carousel/native media tags/collaborators/first comments/trial Reels/is_ai_generated/audio_id/caption add-ons. Instagram caption add-ons (caption_addon, or poll_attachment / is_comment_prompt_used) need a Facebook Login account, a non-empty caption, and a feed photo, Reel, or carousel parent. Stories are rejected. A poll and a comment prompt cannot be combined. For Instagram, @username in caption is only a caption mention; user_tags creates native media tags and collaborators sends co-author invitations only when the selected Meta-linked account reports those capabilities. Call list_platforms with view: "schema" and the account ID first. instagram_settings remains as a backwards-compatible alias.

TIKTOK MEDIA: TikTok supports a single video or a photo slideshow of 1 to 35 images, never multiple videos. Image media auto-detects as a slideshow, so you usually do not set post_type or media_type for photos and every image is posted. Pass platform_settings.media_type: "PHOTO" to force a slideshow explicitly.

Input Schema

NameRequiredDescriptionDefault
captionNoThe post caption/text content. On Instagram, @username is a caption mention, not a native tag or collaborator invite. Optional on Instagram Stories (first slide only in a series). Ignored when `thread_posts` is provided.
confirmYesMust be true after explicit user confirmation of the post/account/workspace/schedule.
platformNoPlatform name (required with username). Supported: instagram, facebook, tiktok, twitter, linkedin, youtube, pinterest, threads, google_business, telegram, bluesky, discord, slack, mastodon, devto, hashnode, wordpress, lemmy. Aliases such as x, gmb, and instagram-standalone are accepted.
usernameNoAccount username (alternative to account_id)
media_urlNoMedia URL to attach. Posterly storage URLs are used as-is; third-party HTTP(S) URLs are copied into posterly storage before the post is saved. Short-lived signed URLs must still be live when this tool runs. For threads, attaches to the lead post only.
post_typeNoOptional post type: text, image, video, carousel, reel, story, story_series, document, photo, cover_photo, x_thread, or threads_thread. Omit it for auto-detection from media. For TikTok photo posts, use photo/image/carousel or omit it; for Facebook cover photos, use cover_photo or platform_settings.post_type.
account_idNoSocial account ID (from list_accounts)
media_urlsNoMultiple media URLs for carousel or multi-image posts. Posterly storage URLs are used as-is; third-party HTTP(S) URLs are copied into posterly storage before the post is saved. For TikTok, 2 or more images auto-create a photo slideshow (up to 35 images) and every image is posted.
scheduled_atNoISO 8601 datetime for scheduling (e.g. 2026-03-05T09:00:00Z). Omit for immediate publish.
thread_postsNoFor X or Threads only: array of 2+ strings, one per post in the thread. The first entry leads, the rest reply in order. When set, the platform must be twitter or threads.
workspace_idNoWorkspace ID to assign the post to (from whoami). If omitted, uses the account's workspace or the caller's default workspace.
platform_settingsNoPlatform-specific settings for the selected account. Use this for non-Instagram settings and prefer it over raw metadata.
instagram_settingsNoInstagram-specific settings. If “tag” is ambiguous, distinguish caption @mentions (put @username in caption), native media tags (user_tags), and co-author invitations (collaborators). Native media tags work with eligible direct or Meta-linked accounts; collaborators require an eligible Meta-linked account. Call list_platforms with view=schema and account_id first.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.55.1

TDQS

A4.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description is unusually rich about consequences: public posting is irreversible after scheduled_at, third-party media URLs are copied into posterly storage, signed URLs must be live at call time, X thread character caps, and Article restrictions. However, it labels itself 'This is a DESTRUCTIVE WRITE' while annotations declare destructiveHint=false, a direct conflict in the safety signal an agent uses to decide how much caution to apply. The contradiction is the reason this dimension is scored low despite the otherwise strong disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded correctly: the irreversible-write warning and the confirmation workflow come first, where an agent will actually read them. The PLATFORM SETTINGS paragraph is a long, comma-spliced enumeration of many platforms that is harder to scan than the rest, but each block is labeled and no sentence is pure filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter tool with deeply nested platform objects and no output schema, the description covers what is needed: identification of the account, scheduling semantics, media handling, threads, Articles, and even post-call behavior (report the dashboard link, do not narrate raw HTTP). Nothing essential to a correct first invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, yet the description still adds cross-parameter semantics the schema cannot express: account_id OR username+platform as alternative identification, workspace_id fallback order (account's workspace, then caller's default), scheduled_at omission meaning immediate publish, caption being ignored when thread_posts is set, and per-platform constraints on platform_settings and instagram_settings.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb pair and resource: 'Schedule or immediately publish a social media post.' An agent immediately knows this is the single-post creation tool and can distinguish it from create_posts_batch (explicitly named later), validate_post, and update_post.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit pre-call sequence (whoami, preview, explicit confirmation, then batch preference) and names alternatives: use create_posts_batch for multiple posts in one turn, upload_media first to reuse a posterly URL, and list_platforms with view:'schema' before platform_settings. It also states a negative rule — do not infer consent from earlier standing instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools