posterly-mcp-server

posterly MCP Server

Use Posterly from any MCP-compatible AI client.

This package gives Claude Desktop, Cursor, Windsurf, Cline, and other local MCP clients a stdio server that can:

• start paid Posterly signup before an API key exists
• poll signup progress while the user completes checkout and password setup
• list connected social accounts
• resolve brands/clients into the right accounts
• schedule and manage posts
• upload media
• generate captions
• generate images
• read account and post analytics

Posterly also exposes the same authenticated toolset over HTTP at poster.ly/mcp, but this npm package is the local stdio connection for desktop AI clients.

Public discovery

• Hosted Streamable HTTP endpoint: https://www.poster.ly/api/mcp
• Server card: https://www.poster.ly/.well-known/mcp/server-card.json
• OpenAPI: https://www.poster.ly/api/openapi
• Agent skills: https://www.poster.ly/.well-known/agent-skills/index.json
• Agent reference: https://www.poster.ly/llms-full.txt
• Signup and API-key acquisition: https://www.poster.ly/agents/signup
• Smithery: https://smithery.ai/servers/awpthorp/posterly
• Source: https://github.com/awpthorp/posterly/tree/main/mcp-server

The official MCP Registry metadata is in server.json. Its canonical registry name is io.github.awpthorp/posterly, matching this package's mcpName.

Requirements

• Node.js 20+
• No API key is required for the public setup tools: get_mcp_status, get_agent_signup_info, start_signup, and get_signup_session
• A Posterly account, API add-on, and API key are required for authenticated tools like whoami, list_accounts, create_connect_session, and create_post

Install

Recommended: use it via npx in your MCP config so your client runs the current server without a global install.

To let an AI agent start signup before a Posterly API key exists, install the server without POSTERLY_API_KEY:

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

After paid signup is complete and Posterly shows an API key, add POSTERLY_API_KEY to unlock the authenticated tools:

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

Quick setup

• Add the Posterly MCP server to your AI client.
• If you do not have Posterly yet, ask the AI to call start_signup.
• Pay in Stripe Checkout and set your Posterly password in the browser.
• When Posterly shows your API key, add it as POSTERLY_API_KEY.
• Restart your AI client.
• Ask the AI to call get_mcp_status, then whoami, then continue by connecting your first social account.

The signup and connect tools return user-facing next steps by default, so agents should report progress in plain language instead of showing raw curl, HTTP payloads, or JSON. Pass debug: true to start_signup, get_signup_session, get_connect_link, create_connect_session, or get_connect_session only when troubleshooting.

Post tools return View in Posterly dashboard links. After scheduling, listing, reading, or deleting posts, share the returned link with the user. Current-month scheduled posts open in Calendar with the post selected; broader/future post views use Table.

Example configs

Claude Desktop

Add this to your Claude Desktop MCP config:

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

Cursor

Add the same server definition to your Cursor MCP settings:

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

Available tools

posterly-mcp-server@0.27.0 exposes 75 tools.

Public setup tools work before POSTERLY_API_KEY exists:

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

Authenticated tools require POSTERLY_API_KEY:

• whoami
• list_accounts
• disconnect_account (disconnect a connected social account after explicit confirmation)
• get_connect_link
• create_connect_session (create a guided browser handoff for connecting a social account)
• get_connect_session (poll connection progress while the user approves OAuth or enters credentials)
• create_api_key (create a new API key after explicit confirmation; scopes cannot exceed the calling dashboard key)
• delete_api_key (revoke a user-created API key after explicit confirmation)
• get_subscription (read subscription status, tier, and cancel/pause state; requires billing:read)
• cancel_subscription (cancel after explicit confirmation; the agent must ask for a reason first; requires billing:write)
• pause_subscription (pause 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 next renewal after confirmation; requires billing:write)
• list_oauth_clients
• create_oauth_client (create a public PKCE client after explicit confirmation)
• update_oauth_client (update redirect URIs/scopes after explicit confirmation)
• delete_oauth_client (delete a developer client after explicit confirmation)
• list_platforms
• get_platform_schema
• trigger_platform_helper
• list_brands
• get_brand
• list_brand_accounts
• get_brand_profile
• get_learned_voice (read the voice learned from one account's real published captions)
• list_posts
• get_post
• get_post_missing
• ask_support (authenticated docs-backed support with read-only account/post diagnostics; human tickets require explicit confirmation)
• create_post (supports thread_posts: string[] for X / Threads reply chains, plus platform_settings for platform-specific composer controls)
• validate_post (checks and normalizes a post without creating it; call before requesting confirmation for create_post)
• submit_agent_feedback (writes bounded private operational telemetry after a real workflow outcome; never include secrets, prompts, captions, media URLs, or personal data)
• create_posts_batch (create up to 25 confirmed posts in one API request)
• update_post (also accepts platform_settings)
• update_post_status (pause, resume, schedule, or draft a post after confirmation)
• update_post_release_id (set/repair external release/group metadata after confirmation)
• delete_post
• delete_post_group (delete grouped draft/scheduled posts after confirmation)
• upload_media
• upload_media_from_url
• create_signed_upload
• find_available_slot
• generate_captions
• generate_image
• get_video_options
• run_video_function (read-only Veo helpers for cost estimation and request validation)
• generate_video (queues a cost-guarded Veo video job)
• get_video_job (poll one job or list recent jobs)
• get_account_analytics
• get_post_analytics
• get_performance_profile (read an account's 90-day performance profile: top formats, timing, caption-length patterns, engagement-rate trend, narrative summary)
• get_post_insights (list per-post feedback-loop insights: performance tier, diagnosis, next action, metrics, baseline)
• list_post_suggestions (list evidence-based weekly post drafts in the account's learned voice, each with a rationale)
• dismiss_suggestion (dismiss a post suggestion after confirmation; never touches one already scheduled)
• list_google_business_reviews
• get_google_business_review_link
• audit_google_business_profile
• suggest_google_business_review_reply
• reply_google_business_review (post/update a public GBP review reply after explicit confirmation)
• delete_google_business_review_reply (delete a GBP review reply after explicit confirmation)
• list_google_business_media (list the photos/videos on a GBP profile gallery)
• add_google_business_media (add a photo/video to a GBP profile gallery from a public URL, after explicit confirmation)
• delete_google_business_media (remove a photo/video from a GBP profile gallery after explicit confirmation)

Google Business tip: pass account_id (the integer id from list_accounts) to every GBP tool. If you use location_id instead, it is the numeric location_id from list_accounts (the GBP location id), not the ChIJ... Place ID that get_google_business_review_link returns. Passing the Place ID resolves to no account and returns "Google Business Profile account not found".

• list_activity
• get_updates (read the latest posterly product updates and news)
• list_webhooks
• create_webhook (create a webhook after explicit confirmation)
• update_webhook (update a webhook after explicit confirmation)
• delete_webhook (delete a webhook after explicit confirmation)
• test_webhook (send a signed test delivery after explicit confirmation)
• get_x_posting_quota

Analytics tools currently support Instagram, Facebook Pages, LinkedIn, Google Business Profile, Pinterest, YouTube, and Threads.

Media uploads

This npm/stdio server can read local file paths. When upload_media receives a larger local file, it automatically requests a signed upload URL and uploads the raw bytes before returning the public media URL.

The hosted HTTP MCP endpoint cannot do that for local files by itself because MCP tool calls are JSON-only. On hosted HTTP MCP, upload_media is for small base64 uploads up to 5MB decoded. For larger media there, use upload_media_from_url for public direct media URLs, or call create_signed_upload only from clients that can also PUT the raw file bytes to the returned upload_url.

What the brand tools are for

Posterly workspaces often have multiple connected accounts under one client or brand.

The brand tools let an assistant work at the same level a human does:

• list_brands lets the agent see clients/brands in the workspace
• get_brand returns summary info for one brand
• list_brand_accounts resolves a brand into the actual connected accounts
• get_brand_profile returns saved brand guidance like tone, audience, keywords, dos and don'ts, and visual notes

This makes prompts like:

• "How is Grassroots doing on Instagram?"
• "Write a post for the Posterly brand voice"
• "Schedule something for our Dubai dental client"

much more reliable than forcing the agent to guess from raw account handles alone.

Example prompts

• What Posterly accounts do I have connected?
• Disconnect the old Instagram account after I confirm the exact account ID
• List my brands in Posterly
• Show me the brand profile for Grassroots
• Find the next 3 posting slots for my LinkedIn account
• Schedule a post for tomorrow at 9am for the Posterly Instagram account
• Pause post 971 after I confirm it is the right scheduled post
• Schedule this as an Instagram Story with a first comment and @partner as collaborator
• Schedule this YouTube video as unlisted, add the thumbnail URL, and put it in our launch playlist
• Post this TikTok with direct-post privacy set to public and stitch disabled
• Schedule these 5 photos as a TikTok (image posts auto-detect as a photo slideshow of 1 to 35 images, no post type needed)
• How did Grassroots perform on Instagram in the last 30 days?
• Ask posterly support why post 3041 failed, but do not raise a human ticket unless I confirm

Pricing

This package uses the Posterly API/MCP add-on:

• $3/month add-on
• 100 create-post requests/hour per API key, with separate media/read limits
• user-created API keys per plan: Starter 1, Pro 2, Power 3, Agency 4
• works across all 18 supported platforms: Instagram, Facebook, TikTok, X, LinkedIn, YouTube, Pinterest, Threads, Google Business, Telegram, Bluesky, Discord, Slack, Mastodon, Dev.to, Hashnode, WordPress, and Lemmy

Each API call counts as one request, so use create_posts_batch when you need to schedule multiple posts in one confirmed operation.

Details: poster.ly/dashboard/api

Links

• Docs: poster.ly/mcp
• OpenClaw skill: poster.ly/openclaw
• API add-on: poster.ly/dashboard/api
• MCP server card: /.well-known/mcp/server-card.json
• OAuth authorization server metadata: /.well-known/oauth-authorization-server
• OAuth protected resource metadata: /.well-known/oauth-protected-resource/api/mcp

Development

From the mcp-server directory:

npm install
npm run build
npm start

The package reads:

• optional POSTERLY_API_KEY for authenticated Posterly tools
• optional POSTERLY_URL if you need to point at a non-production environment