MCP tool reference

47 tools, available over the hosted endpoint or the planpost-mcp npm package. Each is gated by the permissions on your API key, so an agent only sees what the key allows.

connect

claude mcp add --transport http planpost https://mcp.planpo.st/mcp \
  --header "Authorization: Bearer pk_live_xxx"

Posts and publishing 12

list_posts: List your scheduled and published social media posts. Filter by status, platform, campaign, label, post type, or free text.
get_post: Get details of a specific post by ID.
create_post: Create a new social media post. Saves as draft or schedules it for a specific time.
preview_post: Show exactly what each platform will receive for a post: the body after platformContent overrides, the attachments after platformMedia overrides, character count vs the platform limit, whether links are clickable, and the warnings for that platform. Use this to check a post (especially carousels, videos and multi-platform posts) BEFORE scheduling or publishing. Returns structured data plus a dashboard link for the visual preview, it does not return screenshots.
bulk_create_posts: Create a whole campaign of posts from one manifest. Each entry accepts the same fields as create_post; `defaults` supplies values shared by every entry (campaign, connectionIds, timezone, ...) so you don't repeat them. Rows are independent, one bad row fails alone and the rest still get created. Max 50 per call. Returns a per-row result with ids, warnings and edit links.
list_campaigns: List campaign bundles, every campaign tag in use, with post counts by status, the platforms involved and the next scheduled time. Use this to see what a campaign contains before editing or deleting it.
delete_posts: Bulk-delete posts matching a filter, e.g. every draft in a campaign. SAFETY: a filter is required (it will never delete everything), published and processing posts are always excluded, and it runs as a DRY RUN unless confirm:true. Always call once without confirm to see what matches, show the user, then confirm.
update_post: Update a draft or scheduled post.
delete_post: Delete a post.
publish_post: Publish a draft or scheduled post immediately to all connected platforms.
get_posting_schedule: Read the weekly posting queue schedule: the global schedule plus any per-group overrides. Slots are {day: 1-7 (Mon=1..Sun=7), time: 'HH:MM' 24h} in the user's timezone.
set_posting_schedule: Replace the weekly posting queue slots for the global schedule or one account group (Pro; schedule:write). Pass the full desired slot list; an empty array on a group reverts it to inheriting the global schedule.

Connections and groups 9

list_connections: List all connected social media accounts (Instagram, Twitter, LinkedIn, etc.).
list_account_groups: List account groups the user has set up in PlanPost (e.g. 'Polish Pages', 'English Pages'). Each group bundles social connections so you can target multiple accounts in one create_post call. Returns id, name, connectionCount, isDefault, and the underlying connections.
get_account_group: Fetch one account group by id, name, or default flag. Returns the group's connectionIds[] so they can be passed straight to create_post. Name matching is case-insensitive (exact match preferred, substring fallback). If the name is ambiguous the server returns 300 with the candidates.
create_account_group: Create a named account group (e.g. 'Polish Pages') bundling social connections, so future posts can target the whole set at once.
update_account_group: Update an account group's name, description, color, default flag, or replace its full connection list.
delete_account_group: Delete an account group (does not disconnect the underlying social accounts).
add_connections_to_group: Add social connections to an existing account group.
remove_connections_from_group: Remove social connections from an account group.
get_connection_link: Generate a link the user can open in their browser to connect a new social account (OAuth needs a human, send them this link).

Approvals 3

submit_for_approval: Submit a post for human approval. Use this when your API key requires approval (or whenever you want a human to sign off before publishing). Returns an approve link and an approval ID to poll. On approval the post auto-schedules if it has a scheduledFor time.
list_pending_approvals: List posts waiting for approval (and their outcomes). Filter by status to build a review queue.
get_approval_status: Check whether a human has decided on a submitted approval yet (pending / approved / rejected / changes_requested). Poll this after submit_for_approval.

Video and carousels 9

list_video_templates: List available video templates (quotes, hooks, listicles, stories, product showcases, testimonials, promos). Each template describes its editable fields, use them with create_video.
create_video: Submit a video render job from a template. Returns a render ID, poll get_video_status until status is 'completed', then use the returned video URL as post media.
get_video_status: Check the status of a video render job. Completed renders include presigned download URLs for the video and thumbnail (valid ~1 hour).
generate_carousel: Generate carousel slide TEXT (title/content/quote/CTA) from long-form content. Then call render_carousel to turn the slides into branded PNG images in the media library.
list_carousel_styles: List the carousel design system: template families (with content-variant layouts), the 40-palette library (with resolved colors), output formats, font pairings, and slide caps. Use the ids with render_carousel.
render_carousel: Render carousel slides into branded PNG images (server-side, pixel-perfect) saved to the media library. Returns a render ID, poll get_carousel_render until 'completed'. Slide 1 uses the family's cover layout, the last slide its CTA layout, middle slides cycle content variants.
get_carousel_render: Check a carousel render job. When completed, `assets` are full media attachments (id/type/url/key/filename/mimeType/size, in slide order), pass them straight into create_post's `media` array to draft or schedule the carousel post.
list_brand_kits: List saved brand kits (palette, font pairing, logo, handle). Use a kit's id as render_carousel's brandKitId for one-call branded output.
generate_image: Generate an image with AI (DALL-E) for use in posts. Costs 1 AI credit. Returns the image URL, pass it through upload_media/create_post media flow.

Content sources and repurposing 8

list_media: List media you already uploaded, so you can reuse an asset instead of uploading it again. Each item comes back already shaped for create_post's `media` array, pass it straight through.
upload_media: Get a presigned URL to upload an image or video for use in posts.
repurpose_content: Save AI-repurposed content as draft posts. Provide an array of posts with content and target connections.
list_content_sources: List connected content sources (WordPress sites, RSS feeds) used to import content for repurposing.
add_content_source: Connect a WordPress site or RSS feed as a content source. Imported posts can then be repurposed into social content.
delete_content_source: Remove a content source.
fetch_source_content: Import the latest content from a source (e.g. new WordPress posts) right now, then list it with list_imported_content.
list_imported_content: List content already imported from a source, useful as input for repurpose_content or create_post.

Analytics and revenue 4

get_analytics: Get post performance analytics, impressions, likes, comments, shares.
get_revenue_overview: Get revenue analytics: totals and trend vs the previous period, recent transactions, and MRR metrics from connected providers (Stripe / RevenueCat / Shopify). Read-only.
get_best_times: Get the best times to post per platform, based on the user's engagement history. Use before picking scheduledFor in create_post.
suggest_schedule: Ask the smart scheduler to spread N posts across a date range at optimal times. Returns concrete timestamps for create_post.

Brand voice 2

get_brand_voices: List the user's brand voices (tone-of-voice profiles analyzed from their content).
get_brand_voice_prompt: Get the ready-to-use system prompt for a brand voice, apply it when writing posts so the content matches the user's tone.

REST API reference

Posts and publishing 12

list_posts

List your scheduled and published social media posts. Filter by status, platform, campaign, label, post type, or free text.

get_post

Get details of a specific post by ID.

create_post

Create a new social media post. Saves as draft or schedules it for a specific time.

preview_post

Show exactly what each platform will receive for a post: the body after platformContent overrides, the attachments after platformMedia overrides, character count vs the platform limit, whether links are clickable, and the warnings for that platform. Use this to check a post (especially carousels, videos and multi-platform posts) BEFORE scheduling or publishing. Returns structured data plus a dashboard link for the visual preview, it does not return screenshots.

bulk_create_posts

Create a whole campaign of posts from one manifest. Each entry accepts the same fields as create_post; `defaults` supplies values shared by every entry (campaign, connectionIds, timezone, ...) so you don't repeat them. Rows are independent, one bad row fails alone and the rest still get created. Max 50 per call. Returns a per-row result with ids, warnings and edit links.

list_campaigns

List campaign bundles, every campaign tag in use, with post counts by status, the platforms involved and the next scheduled time. Use this to see what a campaign contains before editing or deleting it.

delete_posts

Bulk-delete posts matching a filter, e.g. every draft in a campaign. SAFETY: a filter is required (it will never delete everything), published and processing posts are always excluded, and it runs as a DRY RUN unless confirm:true. Always call once without confirm to see what matches, show the user, then confirm.

update_post

Update a draft or scheduled post.

delete_post

Delete a post.

publish_post

Publish a draft or scheduled post immediately to all connected platforms.

get_posting_schedule

Read the weekly posting queue schedule: the global schedule plus any per-group overrides. Slots are {day: 1-7 (Mon=1..Sun=7), time: 'HH:MM' 24h} in the user's timezone.

set_posting_schedule

Replace the weekly posting queue slots for the global schedule or one account group (Pro; schedule:write). Pass the full desired slot list; an empty array on a group reverts it to inheriting the global schedule.

Connections and groups 9

list_connections

List all connected social media accounts (Instagram, Twitter, LinkedIn, etc.).

list_account_groups

List account groups the user has set up in PlanPost (e.g. 'Polish Pages', 'English Pages'). Each group bundles social connections so you can target multiple accounts in one create_post call. Returns id, name, connectionCount, isDefault, and the underlying connections.

get_account_group

Fetch one account group by id, name, or default flag. Returns the group's connectionIds[] so they can be passed straight to create_post. Name matching is case-insensitive (exact match preferred, substring fallback). If the name is ambiguous the server returns 300 with the candidates.

create_account_group

Create a named account group (e.g. 'Polish Pages') bundling social connections, so future posts can target the whole set at once.

update_account_group

Update an account group's name, description, color, default flag, or replace its full connection list.

delete_account_group

Delete an account group (does not disconnect the underlying social accounts).

add_connections_to_group

Add social connections to an existing account group.

remove_connections_from_group

Remove social connections from an account group.

get_connection_link

Generate a link the user can open in their browser to connect a new social account (OAuth needs a human, send them this link).

Approvals 3

submit_for_approval

Submit a post for human approval. Use this when your API key requires approval (or whenever you want a human to sign off before publishing). Returns an approve link and an approval ID to poll. On approval the post auto-schedules if it has a scheduledFor time.

list_pending_approvals

List posts waiting for approval (and their outcomes). Filter by status to build a review queue.

get_approval_status

Check whether a human has decided on a submitted approval yet (pending / approved / rejected / changes_requested). Poll this after submit_for_approval.

Video and carousels 9

list_video_templates

List available video templates (quotes, hooks, listicles, stories, product showcases, testimonials, promos). Each template describes its editable fields, use them with create_video.

create_video

Submit a video render job from a template. Returns a render ID, poll get_video_status until status is 'completed', then use the returned video URL as post media.

get_video_status

Check the status of a video render job. Completed renders include presigned download URLs for the video and thumbnail (valid ~1 hour).

generate_carousel

Generate carousel slide TEXT (title/content/quote/CTA) from long-form content. Then call render_carousel to turn the slides into branded PNG images in the media library.

list_carousel_styles

List the carousel design system: template families (with content-variant layouts), the 40-palette library (with resolved colors), output formats, font pairings, and slide caps. Use the ids with render_carousel.

render_carousel

Render carousel slides into branded PNG images (server-side, pixel-perfect) saved to the media library. Returns a render ID, poll get_carousel_render until 'completed'. Slide 1 uses the family's cover layout, the last slide its CTA layout, middle slides cycle content variants.

get_carousel_render

Check a carousel render job. When completed, `assets` are full media attachments (id/type/url/key/filename/mimeType/size, in slide order), pass them straight into create_post's `media` array to draft or schedule the carousel post.

list_brand_kits

List saved brand kits (palette, font pairing, logo, handle). Use a kit's id as render_carousel's brandKitId for one-call branded output.

generate_image

Generate an image with AI (DALL-E) for use in posts. Costs 1 AI credit. Returns the image URL, pass it through upload_media/create_post media flow.

Content sources and repurposing 8

list_media

List media you already uploaded, so you can reuse an asset instead of uploading it again. Each item comes back already shaped for create_post's `media` array, pass it straight through.

upload_media

Get a presigned URL to upload an image or video for use in posts.

repurpose_content

Save AI-repurposed content as draft posts. Provide an array of posts with content and target connections.

list_content_sources

List connected content sources (WordPress sites, RSS feeds) used to import content for repurposing.

add_content_source

Connect a WordPress site or RSS feed as a content source. Imported posts can then be repurposed into social content.

delete_content_source

Remove a content source.

fetch_source_content

Import the latest content from a source (e.g. new WordPress posts) right now, then list it with list_imported_content.

list_imported_content

List content already imported from a source, useful as input for repurpose_content or create_post.

Analytics and revenue 4

get_analytics

Get post performance analytics, impressions, likes, comments, shares.

get_revenue_overview

Get revenue analytics: totals and trend vs the previous period, recent transactions, and MRR metrics from connected providers (Stripe / RevenueCat / Shopify). Read-only.

get_best_times

Get the best times to post per platform, based on the user's engagement history. Use before picking scheduledFor in create_post.

suggest_schedule

Ask the smart scheduler to spread N posts across a date range at optimal times. Returns concrete timestamps for create_post.