poster.ly / Posterly

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.

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 paid signup, 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 (62 stdio, 59 hosted HTTP)

The stdio package has 62 tools covering 95 actions; the hosted HTTP endpoint has 59 tools covering 92 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.

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 (PUT the bytes to 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, send the user https://www.poster.ly/drop/<token>, then list_media. 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
list_posts	Posts
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

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

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
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_reviews: Google reviews

View	What it does
reviews (default)	Google reviews
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)

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)

Admin (admin)

API keys, OAuth clients, webhooks, and workspace members.

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

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_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.

Tool	What it does
get_subscription	Subscription
cancel_subscription	Cancel subscription
pause_subscription	Pause subscription
resume_subscription	Resume subscription
downgrade_subscription	Downgrade subscription

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 paid signup
get_signup_session	Check a signup session

Pricing

API + MCP access is an add-on costing $3/month on Starter/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 and licensed audio need a Facebook Login / Meta-linked account. Stories cannot carry a caption add-on.
• 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.
• 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