poster.ly / Posterly MCP

npx add-mcp 'https://www.poster.ly/api/mcp'

posterly MCP Server

Schedule and publish social media posts from Claude Desktop, ChatGPT, Cursor, Windsurf, Cline, or any other MCP-compatible AI client. Two connection options are available: pick the one that fits.

Public plugins and directories

• Cursor community directory: MCP install link, two skills, and a setup command. Separate from the official Cursor Marketplace.
• ClawHub: published OpenClaw skill.
• Smithery: managed hosted MCP connection with your own posterly OAuth sign-in.
• Glama: ownership-verified listing, tool catalog, and client install options.
• Official MCP Registry: published posterly server metadata.
• Public plugin repository: installable Claude Code plugin and Gemini CLI extension.

Official directory submissions for ChatGPT and Claude are under review. The Muse directory application is submitted, with requirements still outstanding. Use the client setup guides for the custom connections available today. API and MCP access needs a posterly plan with API access. New accounts can start with a 7-day free trial: a card is required, you are charged on day 8 unless you start the paid plan sooner, and API and MCP use is limited during the trial.

Connection option 1: stdio (npm package)

For desktop AI clients that spawn an MCP server as a local subprocess.

You do not need a global install. Add this to your client's MCP config and let npx run the current server:

{
  "mcpServers": {
    "posterly": {
      "command": "npx",
      "args": ["-y", "posterly-mcp-server@latest"],
      "env": { "POSTERLY_API_KEY": "pst_live_your_key_here" }
    }
  }
}

If the user has not signed up yet, install the server without POSTERLY_API_KEY. The public tools whoami (with view: "status"), get_agent_signup_info, start_signup, and get_signup_session let an AI check its MCP install, start the 7-day free trial (a card is required, nothing is charged today, charged on day 8 unless the paid plan starts sooner), and poll progress before a posterly API key exists. After the user finishes checkout and password setup, add POSTERLY_API_KEY to unlock scheduling and connection tools.

Agent response style

Signup and connect tools return human-readable next steps by default. Agents should keep the chat clean: send the secure browser links, report progress, and avoid raw curl commands, HTTP payloads, or JSON unless the user explicitly asks to debug.

Use debug: true only when you need raw signup or connect data from start_signup, get_signup_session, create_connect_session, list_platforms (view: "connect_link"), or list_accounts (view: "connect_session").

Scheduling tools return posterly dashboard links. After creating, listing, reading, or deleting posts, share the returned View in posterly link. Current-month scheduled posts open in Calendar with the post selected; general/future views use Table.

Connection option 2: HTTP

For browser-based and cloud AI clients (Claude in Chrome, ChatGPT developer mode apps, Cursor in browser, Grok Bot). Dedicated connect pages: Claude, ChatGPT, Gemini, Cursor, Grok Bot, Poke, Hermes, OpenClaw, Muse (Custom Connector, OpenAPI first, hosted MCP optional), Manus, and Cue. Manus and Cue are Custom MCP by URL (https://www.poster.ly/api/mcp, www required). OAuth is preferred, with a Bearer pst_live_ fallback. Hosted transport is JSON-RPC 2.0 single POST, with no SSE or streamable HTTP in v1. A verified live connect for Manus and Cue is still being validated, and this is not a directory listing. Gemini Spark uses the same URL. OAuth sign-in from gemini.google.com is still being validated. First-schedule walkthroughs: ChatGPT, Claude, Cursor, Poke, Hermes, OpenClaw, Grok Bot Marketplace. Media: Solving the 4MB MCP limit.

• Endpoint: POST https://www.poster.ly/api/mcp
• Wire format: JSON-RPC 2.0 (single request, no SSE in v1)
• Auth header: Authorization: Bearer pst_live_your_key_here
• Capability hint: GET /api/mcp returns server info without auth

curl -s https://www.poster.ly/api/mcp \
  -H "Authorization: Bearer pst_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Managed connection through Smithery

Smithery provides a managed connection to the same hosted HTTP MCP endpoint:

1. Open https://smithery.ai/servers/awpthorp/posterly
2. Add posterly to your Smithery toolbox
3. Sign in to your own posterly account
4. Review the requested scopes and approve the OAuth connection
5. Test with whoami or list_accounts

Each connection belongs to the posterly user who approved it. Other Smithery users cannot access that user's accounts or posts. A paid posterly plan plus the API/MCP add-on is still required.

Full guide: https://www.poster.ly/blog/smithery-social-media-mcp-server

Tools (74 stdio, 71 hosted HTTP)

The stdio package has 74 tools covering 118 actions; the hosted HTTP endpoint has 71 tools covering 115 actions (everything except the three signup tools). Older tool names were merged into these and still work for now: see https://www.poster.ly/docs/integrations/mcp-tool-changes for the old-to-new table and the date they may stop working.

Before auth, the stdio package's public setup tools work without POSTERLY_API_KEY: whoami with view: "status" (installed version, latest npm version, endpoint and API key health), get_agent_signup_info, start_signup, and get_signup_session. Every other tool needs POSTERLY_API_KEY.

How merged tools pick what to do: read tools take a view, write tools take an action, list_jobs takes a type (image or video). update_post changes the status when you pass status, the release metadata when you pass release_id, and client approval when you pass approval_action (owner or admin only, never a brand guest); delete_post deletes a group when you pass group_id and chooses delete_mode (posterly keeps live content; platform also requires confirm_published); upload_media copies a public file when you pass url; list_comments and list_conversations return one item when you pass its ID.

Preview then confirm: actions that post publicly or delete things (comment replies and deletes, DMs, Google review replies and reply deletes, Google profile media, webhook deletes, OAuth client deletes, post group deletes) take two calls. Call without confirm to get a preview and a preview_id, show it to the user, then call again with the same fields plus confirm: true and that preview_id. Previews expire after 10 minutes; public posts can be confirmed once. Other writes keep a single confirm: true after explicit user confirmation.

create_post and create_posts_batch accept an optional idempotency_key. Reuse that same value when a call errors, times out, or the response is lost. If you omit it, an identical create within about 10 minutes returns the original post instead of a second one. The tool result says deduplicated: true and gives the original post id. If you deleted that post in between, the same create makes a new one. When a result is unclear, call get_post or list_posts before creating again. manage_workspace_member does the same for an invite confirm, so a lost reply does not email the teammate twice. The hosted post preview keeps its own key from preview_id; pass idempotency_key only when you want that value used instead.

Tool sets: every tool belongs to one set (core, creative, inbox, google_business, admin, billing, plus signup on stdio). All sets are on by default. Stdio: POSTERLY_TOOLSETS=core,inbox. Hosted with an API key header: /api/mcp?toolsets=core,inbox. OAuth connectors always get every set. Sets only change what is listed; any tool can still be called by name.

Hosted HTTP MCP is JSON on a Vercel route with a ~4MB request body, so hosted upload_media is for small base64 files. For large files use create_signed_upload (one call covers 1 to 20 files; PUT the bytes of each file to its upload_url; plan video caps are Starter 500MB, Pro 750MB, Power 1GB, Agency 4GB), or for ChatGPT web, Claude.ai, and Gemini web laptop files call create_media_drop (one link takes up to 20 files), send the user https://www.poster.ly/drop/<token>, then list_media. In ChatGPT, files from the conversation can go straight to upload_media as chat_files (upload_media_chat_files in the ChatGPT app): ChatGPT passes a short-lived link per file, posterly imports them in order and returns posterly URLs, and a retry reuses files already imported. Use create_media_drop when ChatGPT cannot pass a file. TikTok posts carry url_type: profile_fallback means TikTok has not shared the post link (only the profile is known), so never present it as the post. Longer map: https://www.poster.ly/blog/solving-the-4mb-mcp-limit

Updating a client-approved post reopens the changed review axis (caption edits reopen caption approval, media changes reopen asset approval) so it goes back to pending client review.

Core (core)

Accounts, posting, media, schedule, analytics, and support. What most assistants need.

Tool	What it does
disconnect_account	Disconnect an account
connect_account	Connect with credentials
create_connect_session	Start a connect session
trigger_platform_helper	Run a platform helper
ask_support	Ask support
find_available_slot	Find a free slot
submit_agent_feedback	Agent feedback
submit_product_feedback	Product feedback
validate_post	Validate a post
create_post	Create a post
create_posts_batch	Create posts in bulk
get_x_posting_quota	X posting quota
create_signed_upload	Signed upload link
create_media_drop	Media drop link
list_media	Media library
generate_captions	Generate captions
list_activity	Activity feed
get_credits	AI credits
get_updates	Product updates
posterly_status	Publishing status

whoami: Who am I

View	What it does
identity (default)	You, your scopes, and your workspaces
status	MCP server and connection status

list_accounts: Connected accounts

View	What it does
accounts (default)	Connected accounts
learned_voice	Learned voice of an account
performance_profile	Performance profile of an account
connect_session	Check a connect session

list_platforms: Platforms

View	What it does
platforms (default)	Supported platforms
schema	Platform or account schema
connect_link	Connection links

list_brands: Brands

View	What it does
brands (default)	All brands
brand	One brand
accounts	Brand accounts
profile	Brand profile

manage_brand: Create, update, or archive a brand

Action	What it does
create	Create a brand (admin, after you agree)
update	Rename a brand or change its timezone or website (admin, after you agree)
archive	Archive a brand (admin, preview then confirm). Connected accounts stay connected and scheduled posts still publish

list_posts: Posts

View	What it does
list (default)	Posts, one page at a time
counts	Post counts by day, status, account, and brand

get_post: One post

View	What it does
post (default)	One post
missing	What a post is missing

update_post: Edit a post

Mode (picked by params)	What it does
edit (default)	Edit caption, media, schedule, or settings
status (pass status)	Pause, resume, schedule, or move to draft
release_id (pass release_id)	Set a release or group ID
approval (pass approval_action)	Request, approve, request changes, or reject client review (owner or admin only)

delete_post: Delete posts

Mode (picked by params)	What it does
post (default)	Delete one post. Choose delete_mode: posterly keeps live content; platform also requires confirm_published
group (pass group_id)	Delete a post group (preview then confirm). Never deletes published posts

upload_media: Upload media

Mode (picked by params)	What it does
file (default)	Upload a file
chat_files (pass chat_files)	Import files from the chat (ChatGPT file params, hosted only)
url (pass url)	Upload from a URL

list_analytics: Analytics

View	What it does
accounts	Account analytics
posts	Post analytics
insights	Post insights

Creative (creative)

AI image and video generation, jobs, and post suggestions.

Tool	What it does
list_post_suggestions	Post suggestions
dismiss_suggestion	Dismiss a suggestion
get_video_options	Video options
run_video_function	Video helper
generate_video	Generate a video
generate_image	Generate an image

list_jobs: AI jobs

Type	What it does
image	Image jobs
video	Video jobs

Inbox (inbox)

Social inbox comments and DMs.

list_conversations: Conversations

Mode (picked by params)	What it does
list (default)	List conversations
conversation (pass conversation_id)	One conversation with its messages

manage_conversation: Manage conversations

Action	What it does
send	Send a DM (preview then confirm)
sync	Sync the inbox

list_comments: Comments

Mode (picked by params)	What it does
list (default)	List comments
comment (pass comment_id)	One comment with its replies

manage_comment: Manage comments

Action	What it does
reply	Reply to a comment (preview then confirm)
update	Hide or mark read
delete	Delete a comment (preview then confirm)

Google Business (google_business)

Google Business Profile reviews, media, and audits.

Tool	What it does
audit_google_business_profile	Audit a Google profile
list_google_business_media	Google profile media
list_google_business_service_areas	Google service areas
manage_google_business_service_area	Update Google service areas

list_google_business_service_areas: Google service areas

View	What it does
areas (default)	Towns and postcodes already set on one location
places	Search for a town or postcode to add

manage_google_business_service_area: Update Google service areas

Action	What it does
update	Replace the service area list (preview then confirm)

list_google_business_reviews: Google reviews

View	What it does
reviews (default)	Google reviews, each with review_name for a reply
review_link	Google review link

manage_google_business_review: Manage Google reviews

Action	What it does
suggest_reply	Suggest a reply (never posts)
reply	Reply to a review (preview then confirm)
delete_reply	Delete a review reply (preview then confirm)

Each review from list_google_business_reviews includes review_name (accounts/{account}/locations/{location}/reviews/{review}) plus account_id and location_id when known. Pass that review_name with account_id (or location_id) to manage_google_business_review reply or delete_reply. Do not pass the Place ID from view: "review_link".

manage_google_business_media: Manage Google profile media

Action	What it does
add	Add a photo or video (preview then confirm)
delete	Delete a photo or video (preview then confirm)

list_google_business_locations: Google location hours

Reads regular opening hours and attributes for one location. Stays off until location edits are switched on.

manage_google_business_location: Manage a Google location

Action	What it does
update_hours	Update regular hours (preview then confirm)
update_attributes	Update attributes (preview then confirm)

Admin (admin)

API keys, OAuth clients, webhooks, workspace members, and the publishing pause.

Tool	What it does
create_api_key	Create an API key
delete_api_key	Revoke an API key
list_workspace_members	Workspace members
list_publishing_pauses	Publishing pause
list_oauth_clients	OAuth clients
list_webhooks	Webhooks
create_webhook	Create a webhook

list_webhooks: Webhooks

View	What it does
webhooks (default)	Webhook subscriptions
deliveries	Recent delivery attempts for one webhook. Stays off until delivery history is switched on

manage_workspace_member: Manage a workspace member

Action	What it does
invite	Invite a colleague (preview then confirm)
update	Change role or brands (preview then confirm)
remove	Remove a member or invite (preview then confirm)

manage_publishing_pause: Pause or resume publishing

Action	What it does
pause	Pause publishing
resume	Resume publishing
publish_missed	Publish missed posts now

manage_oauth_client: Manage an OAuth client

Action	What it does
create	Create an OAuth client
update	Update an OAuth client
delete	Delete an OAuth client (preview then confirm)

manage_webhook: Manage a webhook

Action	What it does
update	Update a webhook
delete	Delete a webhook (preview then confirm)
test	Send a test delivery

Billing (billing)

Subscription changes and Agency extra accounts.

Tool	What it does
get_subscription	Subscription, plans above yours with prices, extra accounts (Agency owners) and the exact next steps
cancel_subscription	Cancel subscription
pause_subscription	Pause subscription
resume_subscription	Resume subscription
downgrade_subscription	Downgrade subscription

manage_plan: Plans and the confirm link

Action	What it does
list	Plans, and while trialing the price of starting the paid plan today. Does not charge. Needs billing:read
confirm_link	Return a link the human opens. Does not charge. Needs billing:read

upgrade_subscription: Upgrade subscription

Action	What it does
upgrade	Move to a higher plan: quote the exact charge, then upgrade after confirm: true with the preview_id (preview then confirm)

manage_extra_account: Buy or remove extra accounts

Action	What it does
set	Set extra accounts: quote the exact charge, then buy, raise, lower, or remove them after confirm: true with the preview_id (preview then confirm)

manage_x_posting_addon: Buy an X posting add-on

Action	What it does
buy	Quote the monthly price, then open Stripe Checkout after the user agrees. Nothing is charged until that page is paid. An add-on that is already on opens the billing page for the owner instead.

Signup (signup)

Pre-auth signup for brand-new users. Local npm package only; always on.

Tool	What it does
get_agent_signup_info	Signup info for agents
start_signup	Start a free trial
get_signup_session	Check a signup session

Pricing

API + MCP access is an add-on costing $3/month on Starter, $4/month on Pro, $5/month on Power, or $29/month on Agency (base plans start at $7/month). Create-post endpoints allow 100 requests per hour per key; media writes and read-only calls have separate higher limits. This doesn't mean you can only schedule 100 posts per hour - use create_posts_batch to create up to 25 posts in one confirmed request. User-created API key limits are tier-based: Starter 1, Pro 2, Power 3, Agency 4.

Platform-specific scheduling controls

MCP tools expose the same controls available in posterly's composer through platform_settings:

• Instagram feed, story, reel, carousel, collaborators, user tags, first comment, alt text, trial Reels, Reel covers, parent-container is_ai_generated, licensed Reel audio_id, and caption add-ons (a poll or a comment prompt). Caption add-ons need a Meta (Facebook Login) connection for that Instagram account in this workspace. Accounts connected only through Instagram Login cannot use add-ons. Licensed audio needs a Meta-linked account. Stories cannot carry a caption add-on, but a Story can carry an optional plain caption (same 2,200 character limit and up to 30 hashtags as a feed post; a Story Series sends it with the first slide only).
• Facebook stories, reels, cover photo intent, colored text backgrounds, and Reel covers
• YouTube title, thumbnail, privacy status, made-for-kids, tags, category, optional brandPartner, and playlist (playlist insert stays off unless already enabled)
• LinkedIn document title and filename, organization mentions, video thumbnail, alt text, and content call to action labels including BUY_NOW and SHOP_NOW
• TikTok direct-post privacy, comment/duet/stitch toggles, title, photo slideshows, and commercial disclosure
• Pinterest board, title, destination link, optional product tags, and a required stored JPEG/PNG cover_image_url for video Pins (20 MiB maximum; aliases video_cover_url and pinterest_cover_image_url). Video Pins use registered upload and a media ID, not a public video_url fetch.
• Google Business Profile standard, event, and offer posts with event schedule, offer details, CTA, and EVENT/OFFER recurrence
• X reply settings, polls, paid partnership, and media alt text
• Threads reply controls, text attachments, ghost posts, spoilers, reply approvals, GIPHY attachments, and media alt text
• Telegram polls, parse mode, inline buttons, video cover, start timestamp, live photos, and link-preview controls
• Slack Block Kit markdown and custom blocks
• Mastodon visibility, content warning, quote ID, poll (media plus poll allowed on 4.6+), and instance-supplied text, attachment, and alt-text limits (1,500 characters is only the conservative discovery fallback for alt text). Captions and content warnings are validated rather than silently shortened. Ambiguous final create or upload responses stop automatic retries.
• Dev.to articles with a title, tags, and a canonical URL. The cover and any extra photos are uploaded to Dev.to, up to 25 MB each, and extra photos keep the description you wrote. Dev.to allows 10 image uploads an hour by default. If the cover or an extra photo cannot be uploaded, the article still uses that photo's original image address, and a warning is shown on the post.
• Bluesky languages, media alt text, content labels, hidden tags, quote posts, and quote controls

Auth metadata for agents

• OAuth 2.1 + PKCE flow: https://www.poster.ly/oauth/authorize
• Dynamic Client Registration: https://www.poster.ly/api/oauth/register
• Token endpoint (1-hour access + rotating refresh): https://www.poster.ly/api/oauth/token
• Authorization Server metadata: https://www.poster.ly/.well-known/oauth-authorization-server
• Protected Resource metadata: https://www.poster.ly/.well-known/oauth-protected-resource
• MCP server card: https://www.poster.ly/.well-known/mcp/server-card.json

Get started

1. Sign up: https://www.poster.ly/signup
2. Enable the API add-on at https://www.poster.ly/dashboard/api
3. Generate a key, paste into your client config
4. Restart your AI client and start posting