poster.ly / Posterly MCP

Live MCP/API so AI agents can draft and schedule Instagram/social posts without a dashboard. AI-native social scheduler. Dubai-based.

访问 poster.ly试用此 MCP赞助

托管 MCP 服务器

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

可安装到 Claude Code、Codex、Cursor 等客户端

文档

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 get_mcp_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, get_connect_link, create_connect_session, or get_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, Cursor, Grok Bot, Poke, Hermes, and OpenClaw. 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 (90 stdio, 87 hosted HTTP)

The stdio package includes four public setup tools before auth:

  • get_mcp_status: show the installed server version, latest npm version, MCP endpoint health, API auth health, and update guidance.
  • get_agent_signup_info: explain the safe agent-led signup flow.
  • start_signup: start paid signup and return a Posterly checkout handoff URL plus signup poll URL.
  • get_signup_session: poll checkout, payment, password, and agent-access status.

Authenticated MCP tools require POSTERLY_API_KEY:

  • whoami: confirm auth + see workspaces and scopes.
  • create_api_key: create a new scoped API key after explicit confirmation. The calling key must be a dashboard-created key, and new scopes cannot exceed the calling key.
  • delete_api_key: revoke a user-created API key after explicit confirmation.
  • get_credits: read the AI credit balance for the caller's workspace wallet: available now, included allowance used and remaining, purchased packs, and the next reset (requires billing:read). Read-only, spends nothing.
  • get_subscription: read the posterly subscription status, tier, and cancel/pause state (requires billing:read).
  • cancel_subscription: cancel the subscription after explicit confirmation; the agent asks the user for a reason first (requires billing:write).
  • pause_subscription: pause the subscription for 30 days, one per 90-day cooldown, after confirmation (requires billing:write).
  • resume_subscription: resume a paused subscription (requires billing:write).
  • downgrade_subscription: downgrade one tier at the next renewal after confirmation (requires billing:write).
  • list_accounts: list connected social accounts.
  • disconnect_account: disconnect a connected social account after explicit confirmation.
  • get_connect_link: inspect dashboard connection links, provider readiness, scopes, and connected account counts.
  • connect_account: connect a credential-based account (telegram, bluesky, discord, wordpress, devto, hashnode, lemmy) directly, no browser session needed.
  • create_connect_session: create a guided browser handoff for connecting a social account.
  • get_connect_session: poll connection progress while the user logs in, approves OAuth, or enters credentials.
  • list_oauth_clients / create_oauth_client / update_oauth_client / delete_oauth_client: manage self-serve public OAuth 2.1 + PKCE developer clients after confirmation.
  • list_platforms / get_platform_schema: inspect supported integrations, settings schemas, media limits, helper tools, and planned provider possibilities.
  • trigger_platform_helper: run helper discovery such as Pinterest boards, YouTube playlists, TikTok creator info, LinkedIn recent mentions, or X quota.
  • list_brands: list brands/clients available in your workspaces.
  • get_brand: inspect one brand/client in detail.
  • list_brand_accounts: list the social accounts assigned to a brand/client.
  • get_brand_profile: read the saved brand profile and voice guidance for a brand/client, including learned_voice derived from each connected account's real published captions.
  • get_learned_voice: read the voice learned from one account's real published captions (the "learned captions" shown on the dashboard), keyed by social account ID. Read-only.
  • list_posts / get_post / get_post_missing: browse scheduled content and inspect missing content/settings before publish.
  • ask_support: ask authenticated docs-backed support questions with read-only account/post diagnostics. Human handoff requires explicit confirmation.
  • create_post: schedule or publish one post, including X/Threads chains and platform-specific composer controls.
  • validate_post: validate and normalize one post without creating it; use this before showing the final preview and asking for live-create confirmation.
  • submit_agent_feedback: submit bounded private operational telemetry after a real workflow; never include secrets, prompts, captions, media URLs, or personal data.
  • submit_product_feedback: file a product bug, idea, or feedback on the public board after the user confirms title and category; never use for tool failures (use submit_agent_feedback).
  • create_posts_batch: create up to 25 confirmed posts in one API request, with per-item success or error results.
  • generate_captions: generate or adapt brand-aware caption suggestions without creating a post.
  • update_post / update_post_status / update_post_release_id / delete_post / delete_post_group: manage scheduled content, repair release/group metadata, and clean up grouped drafts/scheduled posts after confirmation. 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.
  • upload_media: small base64 files only. Hosted HTTP MCP is JSON on a Vercel route with a ~4MB request body.
  • upload_media_from_url / create_signed_upload: fetch a public URL (small files), or mint a signed object-storage PUT URL for large files. The PUT to upload_url does not hit the 4MB Vercel body. Plan video caps are Starter 500MB, Pro 750MB, Power 1GB, Agency 4GB. Use create_signed_upload when the client can PUT (Cursor, Claude Code, Codex).
  • create_media_drop / list_media: for ChatGPT web and Claude.ai laptop files, call create_media_drop, send the user https://www.poster.ly/drop/<token>, then list_media. Chat attachments never reach MCP. HEIC and PDF are rejected. Longer map: https://www.poster.ly/blog/solving-the-4mb-mcp-limit
  • find_available_slot: find the next free posting slot honoring 1h gap + preferred hours.
  • generate_image: queues a Railway Nano Banana / Grok job. Gemini quality is model + resolution + thinking_level (quality: "high" turns thinking on). Thinking does not change the credit price. Pass reference_image_urls to lock a logo.
  • get_image_job: poll one queued image job or list recent jobs until urls are ready.
  • get_video_options: inspect read-only Veo video models, input modes, durations, and credit-cost estimates.
  • run_video_function: estimate and validate Veo video jobs before spending credits.
  • generate_video / get_video_job: queue cost-guarded Veo video jobs and poll for the final video_url.
  • get_account_analytics: follower/reach summaries for social platforms, plus native dashboard metrics such as GBP Profile Views, Search Views, Maps Views, Customer Actions, and Posts. Use presentation: "compact" for Telegram/mobile bullets, "table" for Markdown clients, or "json" for custom chart/card renderers.
  • get_post_analytics: per-post likes, comments, reach, impressions. Supports the same presentation modes.
  • get_performance_profile: read an account's 90-day performance profile (top formats, timing, caption-length patterns, engagement-rate trend, narrative summary). Pro plan or higher.
  • get_post_insights: list per-post feedback-loop insights (performance tier, diagnosis, next action, metrics, baseline), filterable by account, post, and checkpoint. Pro plan or higher.
  • list_post_suggestions: list evidence-based weekly post drafts in each account's learned voice, each with a rationale. Pro plan or higher.
  • dismiss_suggestion: dismiss a post suggestion after confirmation; never touches one already scheduled.
  • list_conversations: list Instagram and Facebook Page inbox DMs. Threads has no DMs. Requires a Pro plan or higher.
  • get_conversation: get one inbox conversation and its messages.
  • send_message: send a DM reply after explicit confirmation. Honors Meta 24-hour messaging windows.
  • list_comments: list Instagram, Facebook Page, Threads, and LinkedIn Page inbox comments.
  • get_comment: get one inbox comment and its replies.
  • reply_to_comment: reply to a comment after explicit confirmation. Facebook has no private comment replies; Threads and LinkedIn are public-only.
  • update_comment: hide/unhide a comment or mark it read. Hide is reversible and does not delete. LinkedIn comments cannot be hidden.
  • delete_comment: delete an Instagram or Facebook Page inbox comment after confirmation. Irreversible. Admin only. Threads replies cannot be deleted; hide them with update_comment. LinkedIn comments cannot be deleted.
  • sync_inbox: pull the latest inbox data for one Instagram, Facebook, Threads, or LinkedIn account, with a 30-second cooldown (60 seconds for LinkedIn). Threads and LinkedIn are comments-only (no DMs).
  • list_google_business_reviews: list GBP reviews for one location or every accessible location. Returns every review Google holds (paging past Google's 50-per-page cap), with the full untruncated text and date. Filter by rating/unanswered, page with limit (default 200, max 1000) and offset, and read each location's total_review_count, average_rating, and error.
  • get_google_business_review_link / audit_google_business_profile: generate public review links and run local-profile audits.
  • suggest_google_business_review_reply: draft brand-aware GBP review replies without posting.
  • reply_google_business_review / delete_google_business_review_reply: manage public GBP review replies after explicit confirmation.
  • list_google_business_media: list the photos and videos on a GBP profile gallery.
  • add_google_business_media / delete_google_business_media: add a photo/video to the profile gallery from a public URL, or remove one, after explicit confirmation.
  • list_activity: read the agent notifications feed of post activity, publish attempts, failures, and retries.
  • get_updates: get the latest posterly product updates and news from the updates feed. Requires an active posterly subscription.
  • list_webhooks: inspect webhook subscriptions and delivery status.
  • create_webhook / update_webhook / delete_webhook / test_webhook: manage signed webhook subscriptions after explicit confirmation.
  • get_x_posting_quota: inspect managed X posting allowance and URL-block status.

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, and licensed Reel audio_id (Facebook Login / Meta-linked accounts 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.
  • Bluesky languages, media alt text, content labels, hidden tags, quote posts, and quote controls

Auth metadata for agents

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