posterly-mcp-server

v0.30.0

Published

2 days ago

MCP server for posterly: schedule and publish social media posts across 18 platforms from any MCP client (Claude, ChatGPT, Cursor, Windsurf, Cline, and more)

0High
0Medium
0Low

awpthorp

mcp model-context-protocol posterly social-media scheduling claude cursor chatgpt

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

[email protected] exposes 76 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_credits (read-only AI credit balance)
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

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