PostProxy MCP Server
OfficialThis MCP server exposes the Postproxy API to Claude so it can publish and manage social media posts, comments, DMs, and analytics across many networks.
Auth & workspace:
auth_statusto verify the API key and configuration.Profiles: list profile groups, list profiles (filterable by group), list platform placements (pages, boards, channels, locations), and read profile follower/engagement timeseries.
Publishing:
post_publishwith text, media, scheduling, drafts, queue assignment/priority, idempotency keys, dry-run confirmation, X/Threads threads, and per-platform options (Instagram reels/stories/collaborators, YouTube titles/privacy, TikTok privacy, Facebook pages/stories, LinkedIn orgs, Telegram chat_id/parse mode, Pinterest boards, Google Business posts).Media uploads:
upload_createreturns a temporary upload URL for sandboxed/remote environments.Post lifecycle: get status, update drafts/scheduled posts, delete, delete from platforms only (async), and list recent history.
Analytics:
post_statswith per-network metric snapshots, filters by profile/network and time.Queues: list, get, create, update (timezone, jitter, timeslots, pause), delete, and fetch the next available slot.
Comments: list/get/create replies, delete, hide/unhide, like/unlike on Facebook, Instagram, Threads, YouTube, and LinkedIn.
Profile comments/reviews: Google Business review listing, fetching, replying, and deleting your reply.
Direct messages: list chats, find/create chats, get chats/messages, send (with HUMAN_AGENT tag, Telegram reply/keyboard, media), edit Telegram messages, react/unreact, archive/unarchive on Bluesky, and Meta private replies to commenters.
Coverage gap: the README describes additional tools (e.g.
summary_get, full Google Business listing management, WhatsApp Business management, Instagram audio/collab, Pinterest boards, YouTube playlists) that are not present in this schema.
Provides tools for publishing posts, checking post status, and managing profiles on Bluesky via PostProxy.
Provides tools for publishing posts, checking post status, and managing profiles on Facebook via PostProxy, including placement support for business pages.
Provides tools for publishing posts, checking post status, and managing profiles on Instagram via PostProxy, with support for reels and collaborator tagging.
Provides tools for publishing posts, checking post status, and managing profiles on Pinterest via PostProxy, including board placements.
Provides tools for publishing posts, checking post status, and managing profiles on Telegram via PostProxy, with support for channel placements.
Provides tools for publishing posts, checking post status, and managing profiles on Threads via PostProxy.
Provides tools for publishing posts, checking post status, and managing profiles on TikTok via PostProxy, including privacy and music settings.
Provides tools for publishing posts, checking post status, and managing profiles on YouTube via PostProxy, including video title and privacy settings.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@PostProxy MCP Server Publish 'Launch day!' to Twitter and LinkedIn"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Postproxy MCP Server
MCP (Model Context Protocol) server for integrating Postproxy API with Claude Code. This server provides tools for publishing posts, checking statuses, and managing social media profiles through Claude Code.
Installation
Global Installation
npm install -g postproxy-mcpLocal Installation
npm install postproxy-mcpClaude Code stores MCP server configuration under ~/.claude/plugins/.
After installing postproxy-mcp, Claude will automatically detect the server on restart.
Related MCP server: FastSocial MCP Server
Configuration
Register MCP Server
After installing postproxy-mcp, register it with Claude Code using the claude mcp add command:
claude mcp add --transport stdio postproxy-mcp --env POSTPROXY_API_KEY=your-api-key --env POSTPROXY_BASE_URL=https://api.postproxy.dev/api -- postproxy-mcpReplace your-api-key with your actual Postproxy API key.
The configuration will be automatically saved to ~/.claude/plugins/. After running this command:
Restart your Claude Code session
Test the connection by asking Claude: "Check my Postproxy authentication status"
If tools are available, Claude will be able to use them automatically
Alternative: Interactive Setup
For non-technical users, you can use the interactive setup command:
postproxy-mcp setupor
postproxy-mcp-setupThis will guide you through the setup process step by step and register the server using claude mcp add automatically.
Available Tools
Authentication Tools
auth_status
Check authentication status, API configuration, and workspace information.
Parameters: None
Returns:
{
"authenticated": true,
"base_url": "https://api.postproxy.dev/api",
"profile_groups_count": 2
}Account Overview
summary_get
Answer "what's the status?" in one call — an activity snapshot for a time window instead of separate history_list / comments_list / dm_chats_list round trips.
Parameters:
window(string, optional):24h(default),7d, or30dfrom(string, optional): ISO 8601 timestamp or bare date starting an explicit range. Overrideswindow, and the*_previouscounts come backnullto(string, optional): End of the explicit range. Defaults to now when onlyfromis givenprofile_group_id(string, optional): Report on a single group. Omit to cover every group the key can reach
Returns:
{
"window": {
"label": "24h",
"from": "2026-08-17T09:00:00Z",
"to": "2026-08-18T09:00:00Z",
"previous_from": "2026-08-16T09:00:00Z",
"backlog_from": "2026-07-19T09:00:00Z"
},
"posts": {
"published": 4,
"published_previous": 3,
"failed": 1,
"scheduled_ahead": 6,
"next_scheduled_at": "2026-08-18T14:00:00Z",
"by_platform": { "instagram": { "published": 4, "failed": 0 } }
},
"engagement": {
"total": { "impressions": 48210, "likes": 1204 },
"by_platform": { "instagram": { "impressions": 31002, "likes": 900 } },
"posts_with_insights": 14
},
"comments": { "received": 96, "received_previous": 71, "awaiting_reply": 12, "by_platform": { "instagram": 61 } },
"reviews": { "received": 7, "received_previous": 4, "awaiting_reply": 3 },
"dms": { "inbound": 41, "outbound": 33, "chats_awaiting_reply": 5, "reply_window_closing": 2 },
"api": { "calls": 812, "calls_previous": 640 }
}Notes:
Post counts are posts, so a post sent to three networks counts once and a thread counts once.
by_platformcounts per-network deliveries, so a 3-item X thread is 3 undertwitter.engagementis lifetime-to-date for posts published in the window, not engagement earned during it — it sums each post's newest stats snapshot. A post published minutes ago may have no snapshot yet and won't be inposts_with_insights. Keys are the normalized metrics listed in Stats Fields by Platform.The
awaiting_replycounts describe current state, not the window — they don't change when you changewindow. They look back 30 days, returned aswindow.backlog_from. A comment counts as replied only when the reply came from you (via Postproxy or the profile itself);chats_awaiting_replyis derived from message timestamps, since Postproxy has no read/unread state.reply_window_closingcounts chats with under 6 hours of their 24h messaging window left. Networks without a window (Telegram, Bluesky) are excluded.engagementisnullwhen insights are off for the account;dmsisnullwhen DMs are off.Scoped like every other tool: a group-scoped key reports only its group.
Profile Management
profile_groups_list
List all profile groups accessible with your API key. Profile groups are organizational containers (e.g. per brand or client) that hold related profiles. Use a group's id to filter profiles_list by profile_group_id.
Parameters: None
Returns:
{
"profile_groups": [
{
"id": "grp123abc",
"name": "Main Brand",
"profiles_count": 4
}
]
}profile_groups_initialize_connection
Generate a connect URL for a new profile in a profile group. The user opens the URL to finish the OAuth flow.
Parameters:
profile_group_id(string, required): Profile group IDplatform(string, required): Platform to connect (e.g.instagram,linkedin,whatsapp)onboarding(string, optional): Instagram and WhatsApp only. Instagram:instagram(default) uses Instagram Login;facebookuses Facebook Login, for an Instagram professional account linked to a Facebook Page you manage. The profile isplatform: "instagram"either way, and reconnecting with the other method updates the existing profile in place. WhatsApp:apiorbusiness_app(see WhatsApp Business Management).identifier+app_password(Bluesky) /bot_token(Telegram): credentials, local server only
profiles_list
List all available social media profiles for posting.
Parameters:
profile_group_id(string, optional): If provided, only profiles in this group are returned (useprofile_groups_listto find group IDs)
Returns:
{
"profiles": [
{
"id": "profile-123",
"name": "My Twitter Account",
"platform": "twitter",
"profile_group_id": "group-abc"
}
]
}profiles_placements
List available placements for a profile. For Facebook profiles, placements are business pages. For LinkedIn profiles, placements include the personal profile and organizations. For Pinterest profiles, placements are boards. For Telegram profiles, placements are channels the bot can post to. For Google Business profiles, placements are locations, returned as full resource paths (accounts/X/locations/Y) to pass as location_id. For WhatsApp profiles, placements are the phone numbers on the Business Account — the placement id is the phone_number_id every whatsapp_* tool and dm_chat_create take. Available for facebook, linkedin, pinterest, telegram, google_business, and whatsapp profiles.
Parameters:
profile_id(string, required): Profile hashid
Returns (LinkedIn example):
{
"placements": [
{
"id": null,
"name": "Personal Profile"
},
{
"id": "108520199",
"name": "Acme Marketing"
}
]
}Notes:
If no placement is specified when creating a post:
LinkedIn: defaults to the personal profile
Facebook: defaults to a random connected page (if only one page is connected, no need to set a placement ID)
Pinterest: it fails
Telegram: it fails —
chat_idis required on every postGoogle Business: it fails —
location_idis required on every post and on everygoogle_business_*tool
profiles_stats
Get the follower/engagement timeseries for a profile. Snapshots are captured roughly every 23 hours, so you can plot follower growth and other trends over time. The stats fields are platform-native (not normalized) — see Stats Fields by Platform in the post_stats section for shape and add-on profile-level keys (followers_count, followersCount, etc.) per network.
Parameters:
profile_id(string, required): Profile hashidplacement_id(string, conditional): Required forfacebook,linkedin,telegram, andgoogle_businessprofiles. Get it fromprofiles_placements. Omit forinstagram,threads,youtube,twitter,tiktok,pinterest, andbluesky.from(string, optional): ISO 8601 timestamp — only include snapshots recorded at or after this timeto(string, optional): ISO 8601 timestamp — only include snapshots recorded at or before this time
Returns (LinkedIn example):
{
"data": {
"profile_id": "prof_li_001",
"platform": "linkedin",
"placement_id": "108520199",
"records": [
{ "stats": { "followerCount": 4500, "shareCount": 8, "likeCount": 80 }, "recorded_at": "2026-05-09T08:00:00Z" },
{ "stats": { "followerCount": 4520, "shareCount": 9, "likeCount": 90 }, "recorded_at": "2026-05-10T08:00:00Z" }
]
}
}For non-placement networks (e.g. Bluesky), omit placement_id:
{
"data": {
"profile_id": "prof_bsky_001",
"platform": "bluesky",
"placement_id": null,
"records": [
{ "stats": { "followersCount": 8800, "postsCount": 40 }, "recorded_at": "2026-05-09T08:00:00Z" }
]
}
}Post Management
post_publish
Publish a post to specified social media profiles.
Parameters:
content(string, required): Post content textprofiles(string[], required): Array of profile IDs (hashids) or platform names (e.g.,"linkedin","instagram","twitter"). When using platform names, posts to the first connected profile for that platform.schedule(string, optional): ISO 8601 scheduled timemedia(string[], optional): Array of media URLs or local file pathsidempotency_key(string, optional): Idempotency key for deduplicationrequire_confirmation(boolean, optional): If true, return summary without publishingdraft(boolean, optional): If true, creates a draft post that won't publish automaticallyqueue_id(string, optional): Queue ID to add the post to. The queue will automatically assign a timeslot. Do not use together withschedule.queue_priority(string, optional): Priority when adding to a queue:high,medium(default), orlowplatforms(object, optional): Platform-specific parameters. Key is platform name (e.g., "instagram", "youtube", "tiktok"), value is object with platform-specific options. See Platform Parameters Reference for full documentation.Example:
{ "instagram": { "format": "reel", "collaborators": ["username1", "username2"], "first_comment": "Link in bio!" }, "youtube": { "title": "My Video Title", "privacy_status": "public" }, "tiktok": { "privacy_status": "PUBLIC_TO_EVERYONE", "auto_add_music": true } }
Returns:
{
"post_id": "job-123",
"accepted_at": "2024-01-01T12:00:00Z",
"status": "pending",
"draft": true
}Note on draft posts: If you request a draft post (draft: true) but the API returns draft: false, a warning field will be included in the response indicating that the API may have ignored the draft parameter. This can happen if the API does not support drafts with certain parameters (e.g., media attachments) or under specific conditions. Check the warning field in the response for details.
post_status
Get status of a published post by job ID.
Parameters:
post_id(string, required): Post ID from post.publish response
Returns:
{
"post_id": "job-123",
"overall_status": "complete",
"draft": false,
"status": "processed",
"content": "Full post body as submitted...",
"scheduled_at": "2024-01-02T09:00:00Z",
"created_at": "2024-01-01T12:00:00Z",
"source": "postproxy",
"queue_id": null,
"platforms": [
{
"platform": "twitter",
"status": "published",
"url": "https://twitter.com/status/123",
"post_id": "123",
"error": null,
"attempted_at": "2024-01-01T12:00:00Z"
}
]
}scheduled_at is null for posts published immediately. Platform url is the published permalink (null until published).
Status values:
overall_status:"draft","pending","processing","complete","failed"Platform
status:"pending","processing","published","failed","deleted"Platform
error: Error message if publishing failed (null if successful)
post_publish_draft
Publish a draft post. Only posts with draft: true status can be published using this endpoint.
Parameters:
post_id(string, required): Post ID of the draft post to publish
Returns:
{
"post_id": "job-123",
"status": "processed",
"draft": false,
"scheduled_at": null,
"created_at": "2024-01-01T12:00:00Z",
"message": "Draft post published successfully"
}post_delete
Delete a post by job ID.
Parameters:
post_id(string, required): Post ID to delete
Returns:
{
"post_id": "job-123",
"deleted": true
}post_stats
Get stats snapshots for one or more posts. Returns all matching snapshots so you can see trends over time. Supports filtering by profiles/networks and timespan.
Parameters:
post_ids(string[], required): Array of post hashids (max 50)profiles(string, optional): Comma-separated list of profile hashids or network names (e.g.instagram,twitterorabc123,def456or mixed)from(string, optional): ISO 8601 timestamp — only include snapshots recorded at or after this timeto(string, optional): ISO 8601 timestamp — only include snapshots recorded at or before this time
Returns:
{
"data": {
"abc123": {
"platforms": [
{
"profile_id": "prof_abc",
"platform": "instagram",
"records": [
{
"stats": {
"impressions": 1200,
"likes": 85,
"comments": 12,
"saved": 8
},
"recorded_at": "2026-02-20T12:00:00Z"
}
]
}
]
}
}
}Stats fields by platform:
Platform | Fields |
| |
| |
Threads |
|
| |
YouTube |
|
| |
TikTok |
|
|
Notes: Instagram stories do not return stats. TikTok stats require the post to have a public ID.
Queue Management
queues_list
List all posting queues. Queues automatically schedule posts into recurring weekly timeslots with priority-based ordering.
Parameters:
profile_group_id(string, optional): Filter queues by profile group
Returns:
{
"queues": [
{
"id": "q1abc",
"name": "Morning Posts",
"description": "Daily morning content",
"timezone": "America/New_York",
"enabled": true,
"jitter": 10,
"profile_group_id": "pg123",
"timeslots": ["Monday at 09:00 (id: 1)", "Wednesday at 09:00 (id: 2)"],
"posts_count": 5
}
]
}queues_get
Get details of a single posting queue including its timeslots and post count.
Parameters:
queue_id(string, required): Queue ID
queues_create
Create a new posting queue with weekly timeslots.
Parameters:
profile_group_id(string, required): Profile group ID to connect the queue to (useprofiles_listto find this)name(string, required): Queue namedescription(string, optional): Optional descriptiontimezone(string, optional): IANA timezone name (e.g.America/New_York). Default:UTCjitter(number, optional): Random offset in minutes (0–60) applied to scheduled times for natural posting patterns. Default:0timeslots(array, optional): Initial weekly timeslots. Each object hasday(0=Sunday through 6=Saturday) andtime(24-hourHH:MMformat)
Example:
{
"profile_group_id": "pg123",
"name": "Weekday Mornings",
"timezone": "America/New_York",
"jitter": 10,
"timeslots": [
{ "day": 1, "time": "09:00" },
{ "day": 2, "time": "09:00" },
{ "day": 3, "time": "09:00" },
{ "day": 4, "time": "09:00" },
{ "day": 5, "time": "09:00" }
]
}queues_update
Update a queue's settings, timeslots, or pause/unpause it. Changes to timezone or timeslots trigger rearrangement of all queued posts.
Parameters:
queue_id(string, required): Queue ID to updatename(string, optional): New queue namedescription(string, optional): New descriptiontimezone(string, optional): IANA timezone nameenabled(boolean, optional): Set tofalseto pause the queue,trueto unpausejitter(number, optional): Random offset in minutes (0–60)timeslots(array, optional): Timeslots to add or remove. To add:{ "day": 1, "time": "09:00" }. To remove:{ "id": 42, "_destroy": true }.
queues_delete
Delete a posting queue. Posts in the queue will have their queue reference removed but will not be deleted.
Parameters:
queue_id(string, required): Queue ID to delete
queues_next_slot
Get the next available timeslot for a queue.
Parameters:
queue_id(string, required): Queue ID
Returns:
{
"next_slot": "2026-03-11T14:00:00Z"
}Adding Posts to a Queue
When publishing a post with post_publish, you can add it to a queue instead of scheduling it manually:
queue_id(string, optional): Queue ID to add the post to. The queue will automatically assign a timeslot. Do not use together withschedule.queue_priority(string, optional): Priority level:high,medium(default), orlow. Higher priority posts get earlier timeslots.
Example:
{
"content": "Queued post content",
"profiles": ["twitter", "linkedin"],
"queue_id": "q1abc",
"queue_priority": "high"
}Comment Management
comments_list
List comments on a published post. Returns paginated top-level comments with nested replies.
Parameters:
post_id(string, required): Post IDprofile_id(string, required): Profile ID to identify which platform's comments to retrievepage(number, optional): Page number, zero-indexed (default: 0)per_page(number, optional): Number of top-level comments per page (default: 20)from(string, optional): ISO 8601 date/time — only comments received at or after this pointto(string, optional): ISO 8601 date/time — only comments received at or before this point
from/to filter on when Postproxy received the comment, not the platform's posted_at (which isn't always populated). A bare date such as 2026-03-25 means that date's start of day. The filter applies to top-level comments only — a comment in range still returns its full replies array.
Returns:
{
"total": 42,
"page": 0,
"per_page": 20,
"data": [
{
"id": "cmt_abc123",
"external_id": "17858893269123456",
"body": "Great post!",
"status": "synced",
"author_username": "someuser",
"like_count": 3,
"is_hidden": false,
"posted_at": "2026-03-25T10:00:00.000Z",
"replies": [
{
"id": "cmt_def456",
"body": "Thanks!",
"author_username": "author",
"parent_external_id": "17858893269123456"
}
]
}
]
}Comment objects may also include an attachments array (media on the comment — image, video, audio, gif, external, file), each with id, type, url, status, and external_id. Populated for Facebook, Threads, and Bluesky; Instagram, YouTube, and LinkedIn comments are text-only. The array is empty when there is no media.
comments_get
Get a single comment with its replies.
Parameters:
post_id(string, required): Post IDcomment_id(string, required): Comment ID (Postproxy ID or platform external ID)profile_id(string, required): Profile ID
comments_create
Create a comment or reply on a published post. The comment is published to the platform asynchronously.
Parameters:
post_id(string, required): Post IDprofile_id(string, required): Profile IDtext(string, required): Comment text contentparent_id(string, optional): ID of comment to reply to (Postproxy ID or external ID). Omit to comment on the post itself.
Returns:
{
"id": "cmt_ghi789",
"body": "Thanks for the feedback everyone!",
"status": "pending",
"external_id": null
}The comment is created with status: "pending". Once published to the platform, it becomes "published". If publishing fails, it becomes "failed".
comments_delete
Delete a comment from the platform asynchronously. Supported on Instagram, Facebook, YouTube, and LinkedIn. Not supported on Threads.
Parameters:
post_id(string, required): Post IDcomment_id(string, required): Comment ID (Postproxy ID or external ID)profile_id(string, required): Profile ID
comments_edit
Edit the text of a comment you published, asynchronously. Supported on Facebook and YouTube only. Returns { accepted: true }; the outcome arrives via comment.edited / comment.edit_failed webhooks.
Parameters:
post_id(string, required): Post IDcomment_id(string, required): Comment ID (Postproxy ID or external ID)profile_id(string, required): Profile IDbody(string, required): New comment text
comments_hide
Hide a comment on the platform asynchronously. Supported on Instagram, Facebook, and Threads.
Parameters:
post_id(string, required): Post IDcomment_id(string, required): Comment IDprofile_id(string, required): Profile ID
comments_unhide
Unhide a previously hidden comment. Supported on Instagram, Facebook, and Threads.
Parameters:
post_id(string, required): Post IDcomment_id(string, required): Comment IDprofile_id(string, required): Profile ID
comments_like
Like a comment on the platform asynchronously. Currently only supported on Facebook.
Parameters:
post_id(string, required): Post IDcomment_id(string, required): Comment IDprofile_id(string, required): Profile ID
comments_unlike
Remove a like from a comment. Currently only supported on Facebook.
Parameters:
post_id(string, required): Post IDcomment_id(string, required): Comment IDprofile_id(string, required): Profile ID
Platform Support
Action | Threads | YouTube | |||
List | Yes | Yes | Yes | Yes | Yes |
Reply | Yes | Yes | Yes | Yes | Yes |
Delete | Yes | Yes | No | Yes | Yes |
Hide/Unhide | Yes | Yes | Yes | No | No |
Like/Unlike | No | Yes | No | No | No |
Direct Messages
1:1 messaging (chats and messages) on DM-capable profiles. Supported on Facebook (Messenger), Instagram (DMs), Telegram (Bot DMs), Bluesky, and WhatsApp. Outbound sends are processed asynchronously (returned with status: "pending"). Meta's 24h messaging window applies to Facebook/Instagram — a human replying to the participant's own inquiry can pass tag: "HUMAN_AGENT" to send outside it (up to 7 days, never for promotional or automated content); Telegram and Bluesky have no window. On WhatsApp the window is re-opened only by sending an approved template (template) or a category: "utility" text — see WhatsApp Business Management for the rest of the WhatsApp surface.
dm_chats_list
List chats for a profile, ordered by most recent activity.
Parameters:
profile_id(string, required): Profile ID (Facebook, Instagram, Telegram, Bluesky, or WhatsApp)page(number, optional): Page number, zero-indexed (default: 0)per_page(number, optional): Items per page (default: 20)before/after(string, optional): ISO 8601 timestamp filters onlast_message_at
WhatsApp chats also carry external_placement_id (the phone number the chat belongs to), group (true for group chats) and within_messaging_window.
dm_chat_create
Find or create a chat for a participant (idempotent — returns the existing chat if one exists). Use before messaging a participant the profile hasn't messaged yet.
Parameters:
profile_id(string, required): Profile IDparticipant_external_id(string, required): Platform participant ID (IG-scoped user ID, Facebook PSID, Telegram user id, Bluesky DID, or a WhatsApp phone number with country code — non-digits are stripped)placement_id(string, optional): Placement id fromprofiles_placements. Required on WhatsApp (the phone number the chat is on); optional on Facebook (page id)participant_username(string, optional)participant_name(string, optional)
A brand-new WhatsApp conversation has no open messaging window, so the first send into it must be a template (see dm_message_send).
dm_chat_get
Get a single chat by Postproxy ID or platform external_conversation_id.
Parameters:
chat_id(string, required): Chat ID or external conversation ID
dm_messages_list
List messages in a chat, most recent first.
Parameters:
chat_id(string, required): Chat ID or external conversation IDpage(number, optional): Page number, zero-indexed (default: 0)per_page(number, optional): Items per page (default: 20)direction(string, optional):inboundoroutboundstatus(string, optional): Filter by message status
dm_message_send
Send an outbound message. Provide exactly one of body (text), media (a single attachment), or — on WhatsApp — template, interactive, location or contacts.
Parameters:
chat_id(string, required): Chat ID or external conversation IDbody(string, optional): Message text (required when nothing else is sent; on WhatsApp it may also accompanymediaas the caption)media(string[], optional): Up to one attachment as a URL or local file path. Not supported on Bluesky. (The remote/Worker MCP accepts URLs only.) WhatsApp limits: image 5MB jpeg/png, video 16MB mp4/3gpp, audio 16MB, document 100MB.tag(string, optional):HUMAN_AGENTto send outside the 24h window — extends it to 7 days from the participant's last inbound message (Facebook/Instagram only). Meta restricts it to a human replying to the participant's own inquiry; using it for marketing, offers, or automated re-engagement can get that Page / Instagram account's messaging capability suspended. Past 7 days Meta rejects the send and the message lands instatus: failedwith the platform error inerror_details.reply_to_external_id(string, optional): Telegram, WhatsApp & Instagram — platform message id (Telegrammessage_id, WhatsAppwamid, Instagrammid) to quote / thread underreply_markup(object, optional): Telegram only — inline/reply keyboard payloadquick_replies(object[], optional): Facebook & Instagram only — up to 13 tappable chips above the participant's composer. Each{ title, payload }.buttons(object[], optional): Facebook & Instagram only — up to 3 buttons attached to the message. Each{ type: "web_url", title, url }or{ type: "postback", title, payload }.card(object, optional): Facebook & Instagram only — extra fields for the card carryingbuttons(subtitle,image_url,default_action). Requiresbuttons.template(object, optional): WhatsApp only — send an approved template:{ id | name, language, variables[], button_params[], header_media, header_location }. The only way to message outside the 24h window or to open a new conversation.interactive(object, optional): WhatsApp only — Meta-shaped interactive message (reply buttons, list, cta_url, product, flow, location request), passed through unchangedlocation(object, optional): WhatsApp only —{ latitude, longitude, name, address }contacts(object[], optional): WhatsApp only — contact cards in Meta'scontactsshapecategory(string, optional): WhatsApp only —"utility"marks a plain text send as a utility Direct Send that may go outside the window without a templatelink_preview(boolean, optional): WhatsApp only —falsesuppresses the URL preview on a text messagevoice_note(boolean, optional): WhatsApp only — deliver an OGG/Opus audio attachment as a voice notefilename(string, optional): WhatsApp only — display name for a document attachment
Quick replies and buttons
Facebook Messenger and Instagram Direct only — on Telegram use reply_markup instead (passing these returns a 422). Quick replies are ephemeral chips that vanish once one is tapped; buttons stay attached to the message in the thread.
|
| |
Max per send | 13 | 3 |
| required, ≤20 chars | required, ≤20 chars |
| required, ≤1000 chars | required for |
| — | required for |
Needs | no | yes, and |
With | Facebook only | not allowed |
{
"chat_id": "chat_xyz789",
"body": "What can I help with?",
"quick_replies": [
{ "title": "Track order", "payload": "TRACK" },
{ "title": "Talk to support", "payload": "HELP" }
]
}{
"chat_id": "chat_xyz789",
"body": "Nike Air Max",
"card": { "subtitle": "$129 · Arriving Friday", "image_url": "https://cdn.example.com/shoe.png" },
"buttons": [
{ "type": "web_url", "title": "Buy now", "url": "https://shop.example.com/p/air-max" },
{ "type": "postback", "title": "Notify me", "payload": "NOTIFY:air-max" }
]
}Buttons are delivered as a Meta generic template whose element title is your body — that's where the 80-character cap comes from. Instagram is stricter than Messenger: it delivers quick replies only on a plain-text message, so quick_replies with media or with buttons returns 422 there.
Receiving taps: a tapped chip or button postback arrives as an inbound message carrying tapped_action: { "kind": "quick_reply" | "postback" | "callback_query", "payload": "...", "title": "..." }. Read it from dm_messages_list / dm_message_get instead of digging through platform_data. Instagram ice-breaker taps and Telegram callback queries normalize to the same field.
WhatsApp templates and interactive messages
A WhatsApp number can only send free-form text, media, interactive, location and contacts while the participant's 24h window is open (within_messaging_window on the chat). Outside it — including a conversation you start yourself — send an approved template. variables fill the placeholders in order (header text vars first, then body vars, then dynamic URL button vars) and must match the template's variable_count from whatsapp_templates_list; the rendered body is stored on the message.
{
"chat_id": "chat_wa1",
"template": {
"name": "order_update",
"language": "en_US",
"variables": ["Ana", "ORD-12345"]
}
}Templates with a media header take header_media: { "link": "https://..." }; a location header takes header_location; URL / copy-code / flow buttons take button_params: [{ "index": 0, "sub_type": "url", "parameters": [{ "type": "text", "text": "12345" }] }].
Inside the window, interactive is Meta's own object — reply buttons (up to 3), a list (up to 10 rows), a CTA URL, a product card, a flow or a location request:
{
"chat_id": "chat_wa1",
"interactive": {
"type": "button",
"body": { "text": "Ready to confirm your booking?" },
"action": {
"buttons": [
{ "type": "reply", "reply": { "id": "confirm", "title": "Confirm" } },
{ "type": "reply", "reply": { "id": "reschedule", "title": "Reschedule" } }
]
}
}
}A tap comes back as an inbound message whose body is the tapped title, with the reply id under platform_data.interactive. Facebook/Instagram quick_replies / buttons return 422 on WhatsApp, and template / interactive / location / contacts / category return 422 on every other network.
dm_message_get
Get a single message by Postproxy ID or platform external_id.
Parameters:
message_id(string, required): Message ID or external ID
dm_message_edit
Edit a previously-sent outbound message. Telegram only. Provide body and/or reply_markup (pass {} to clear the keyboard); at least one is required.
Parameters:
message_id(string, required): Message ID or external IDbody(string, optional): New text/captionreply_markup(object, optional): New keyboard (or{}to remove)
dm_message_react / dm_message_unreact
Add or remove your business account's reaction on a message. Facebook Messenger, Instagram Direct and WhatsApp.
Parameters (dm_message_react):
message_id(string, required): Message ID or external IDreaction(string, optional): Named reaction (defaultlove). Ignored on WhatsAppemoji(string, optional): Unicode emoji. Required on WhatsApp (any emoji)
Parameters (dm_message_unreact):
message_id(string, required)
dm_chat_archive / dm_chat_unarchive
Archive (mute) or unarchive (unmute) a chat. Bluesky only. Returns the chat with archived set.
Parameters:
chat_id(string, required): Chat ID or external conversation ID
dm_chat_mark_read
Mark a chat as read. On WhatsApp this sends the read receipt (blue ticks) for the newest inbound message; on other networks it only stamps metadata.read_at. Returns the chat.
Parameters:
chat_id(string, required): Chat ID or external conversation ID
dm_comment_private_reply
Send a DM to the author of a comment, in reply to that comment (Meta "Private Replies"). Bypasses the 24h window (comments up to 7 days old) and creates/reuses a chat automatically. One private reply per comment, ever. Instagram and Facebook only.
Parameters:
post_id(string, required): Post IDcomment_id(string, required): Comment ID or external IDprofile_id(string, required): Profile ID (Instagram or Facebook)text(string, required): DM textquick_replies(array, optional): Up to 13 chips — same shape asdm_message_sendbuttons(array, optional): Up to 3 buttons — same shape asdm_message_send; capstextat 80 characterscard(object, optional): Card styling forbuttons(subtitle,image_url,default_action)
Interactive elements follow the same rules as dm_message_send — on Instagram, quick_replies and buttons are mutually exclusive. Media attachments are not available on private replies.
Thread control (Facebook & Instagram)
Meta lets several apps share a Page's or Instagram account's inbox (Postproxy, Meta's inbox, chatbots like ManyChat), but only one controls a conversation at a time. Messages still reach Postproxy while another app holds it, but sends are rejected until control comes back.
Tool | Purpose |
| Hand the conversation to |
| Take it back from whichever app holds it — needs Conversation Routing on the Page; Facebook and Facebook-Login Instagram only |
| Give up control; the conversation goes idle |
| Ask the owner app to pass it — only when the Page does not use Conversation Routing; Facebook and Facebook-Login Instagram only |
| Ask Meta who controls the conversation now ( |
Each takes chat_id and an optional metadata note forwarded to the receiving app. The four control actions return the chat with metadata.thread_control refreshed.
Platform Support
Action | Telegram | Bluesky | |||
List/Send/Get | Yes | Yes | Yes | Yes | Yes |
Media attachment | Yes | Yes | Yes | No | Yes (caption allowed) |
Edit message | No | No | Yes | No | No |
React/Unreact | Yes | Yes | No | No | Yes ( |
Archive/Unarchive | No | No | No | Yes | No |
Mark read (receipt sent) | local only | local only | local only | local only | Yes |
Private reply to comment | Yes | Yes | No | No | No |
| Yes | Yes | n/a | n/a | No — use |
| No | Yes | Yes | No | Yes |
| No | No | Yes | No | No |
| Yes | Yes (text-only) | No | No | No — use |
| No | No | No | No | Yes |
| Yes | Yes | Yes | No | No (see |
History
history_list
List recent post jobs.
Parameters:
limit(number, optional): Maximum number of jobs to return (default: 10)
Returns:
{
"jobs": [
{
"post_id": "job-123",
"content": "Full post body as submitted...",
"content_preview": "Post content preview...",
"created_at": "2024-01-01T12:00:00Z",
"overall_status": "complete",
"status": "processed",
"scheduled_at": "2024-01-02T09:00:00Z",
"draft": false,
"source": "postproxy",
"queue_id": null,
"platforms_count": 2,
"platforms": [
{
"platform": "twitter",
"status": "published",
"url": "https://x.com/user/status/123"
}
]
}
]
}scheduled_at is null for posts that were published immediately. status is the raw API status (draft, scheduled, processing, processed, …), while overall_status folds platform outcomes into a single verdict.
Note: Postproxy's
/postsAPI does not return profile identity (profile ID or name) per platform — only the network. Useprofiles_listto map networks to connected profiles.
Google Business Profile Management
These edit the Google business listing itself — hours, attributes, services, food menus, action links and profile photos — as opposed to publishing local posts to it (that's post_publish with platform google_business).
Three rules apply to every tool in this group:
location_idis always required. It's the full Google resource pathaccounts/X/locations/Y, returned byprofiles_placements.Updates are field-masked. Each write takes a
fieldsarray naming exactly what's being replaced. Anything named infieldsbut absent from the payload is cleared, and nested objects are replaced wholesale rather than merged. Always read before you patch.Availability varies by category and region. Attributes, service lists, food menus and action link types differ per listing. List what's available first; a location that isn't eligible returns
422.
Payloads use Google's own shapes and camelCased keys in both directions, so a response can be sent straight back as a request body.
Tool | Purpose |
| Read the listing — name, description, website, phones, categories, address, hours, service area, metadata |
| Update listing fields ( |
| Resolve category resource names ( |
| Set |
| Read attributes currently set |
| List which attributes this listing can set, with value types |
| Set attributes |
| Read the service list |
| Replace the service list (needs |
| Read food menus (restaurant-like categories only) |
| Replace food menus (needs |
| List action buttons ("Book online", "Order online") |
| List action types Google accepts for the location |
| Add an action button |
| Update an action button |
| Remove an action button |
| List profile photos and videos |
| Add a photo or video |
| Remove a photo or video |
| Monthly search keywords that surfaced the location in Search and Maps (up to 12 months per call, last 18 months available) |
Typical flow
1. profiles_placements → get location_id
2. google_business_location_get → read current state
3. google_business_attributes_available → see what this listing accepts
4. google_business_attributes_update → patch only what changedAttribute value shapes
google_business_attributes_available returns a valueType per attribute, which decides the shape to send back:
valueType | Shape |
|
|
|
|
|
|
attribute_mask defaults to exactly the names you send, so a partial update never clears attributes you left out.
Hours
Times accept either "09:00" / "09:00:00" strings or Google's { "hours": 9, "minutes": 0 } objects — both are normalized before the call. Read current hours from google_business_location_get; each block named in fields is replaced entirely.
{
"fields": ["regularHours"],
"regularHours": {
"periods": [
{ "openDay": "MONDAY", "openTime": "09:00", "closeDay": "MONDAY", "closeTime": "18:00" }
]
}
}Media
Google downloads the file from media_url itself — there is no upload step, so the URL must be publicly reachable https (not a short-lived signed URL, not localhost). Images need at least 250×250 and at most 5MB. category defaults to ADDITIONAL; use COVER or LOGO only when you intend to change the profile header or logo.
Reading empty results
Google omits keys rather than returning empty values: a listing with no attributes returns { "name": "..." } with no attributes key at all, and the same applies to serviceItems, placeActionLinks and boolean flags like isPreferred. Treat absent as empty.
Analytics
Google Business location analytics come through the standard profiles_stats tool — pass the location_id as placement_id. Metrics are Search and Maps impressions (desktop and mobile), website clicks, call clicks, direction requests, conversations, bookings, food orders and food-menu clicks. Google Business has no follower count, and Google exposes no per-post analytics for local posts. For the search terms people used to find the location, use google_business_search_keywords.
WhatsApp Business Management
Manage a connected WhatsApp Business Account beyond the inbox: message templates, phone-number status and registration, the public business profile, display name and username, blocked users, groups, and Click-to-WhatsApp conversion reporting. Conversations themselves go through the dm_* tools above.
Four rules apply to every tool in this group:
The WhatsApp Business Account (WABA) is the profile; each phone number on it is a placement. Phone-scoped tools take
phone_number_id— the placementidfromprofiles_placements(its metadata carriesdisplay_phone_number,quality_rating,messaging_limit_tier,name_status,platform_type).Templates and the Conversions dataset are WABA-level — those tools take only
profile_id.Free-form messages only inside the 24h window. Once a participant's last inbound message is older than 24h (or the conversation is new),
dm_message_sendaccepts only an APPROVEDtemplate(or acategory: "utility"text). A delivered template re-opens the window.Coexistence numbers are limited. A number connected with
onboarding: "business_app"(still in the WhatsApp Business app on a phone) has lower throughput and cannot use the Groups API;whatsapp_number_inforeportsplatform_typeother thanCLOUD_APIfor these.
Responses use Meta's own field names where Meta's shapes are returned (components, interactive, business profile fields).
Tool | Purpose |
| List synced templates (filter |
| One template with components, status and |
| Submit a custom template ( |
| Change |
| Delete one language ( |
| Inspect a Meta library template before instantiating it |
| Live number + WABA status: quality rating, messaging tier, name status, platform type |
| Register the number with the Cloud API using its 6-digit PIN |
| SMS / voice verification code for an unverified number |
| Submit the verification code |
| Public profile: about, address, description, email, websites, vertical, photo |
| Update those fields ( |
| Replace the profile photo ( |
| Verified display name and review status |
| Submit a new display name for Meta review |
| Manage the number's |
| Who is blocked |
| Block / unblock up to 1000 numbers per call |
| Groups the number administers (Cloud API numbers only) |
| Manage members (a group holds 8) |
| Fresh invite link (revokes the previous one) |
| Handle join requests on approval-required groups |
| Conversions API dataset on the WABA |
| Report a LeadSubmitted / Purchase / AddToCart / InitiateCheckout / ViewContent for a Click-to-WhatsApp conversation |
Typical flow
1. profile_groups_initialize_connection → platform: whatsapp (onboarding: api | business_app)
2. profiles_placements → get phone_number_id
3. whatsapp_templates_list → find an APPROVED template and its variable_count
4. dm_chat_create → participant_external_id: phone, placement_id: phone_number_id
5. dm_message_send → template: { name, language, variables }
6. dm_messages_list → the reply opens a 24h window; free-form sends now workConnecting a number
profile_groups_initialize_connection with platform: "whatsapp" returns a connect URL. Pass onboarding: "business_app" when the number lives in the WhatsApp Business app on a phone (the user scans a QR code; the app keeps working alongside Postproxy and up to 6 months of chats are imported) or onboarding: "api" when the number is with another provider or brand new (moved onto the Cloud API; no longer usable in the app). Omit it and the connect page asks. Each WhatsApp Business Account becomes one profile and each of its numbers a placement.
Templates
Meta reviews every custom template; a new one is PENDING until approved, and only APPROVED templates can be sent. Placeholders are {{1}}, {{2}}… (parameter_format: POSITIONAL, the default) or {{name}} (NAMED). variable_count on a template is the number of variables a send must carry: header text placeholders, then body placeholders, then one per dynamic-URL button. Library templates (whatsapp_template_library_get → whatsapp_template_create with library_template_name) skip review. A name is unique per language; deleting by name without language removes every language.
Conversions
Conversations that start from a Click-to-WhatsApp ad carry a ctwa_clid on the chat's metadata. Create a dataset once (whatsapp_dataset_create), then report outcomes with whatsapp_conversion_event_send by chat_id or phone; a chat with no captured ctwa_clid returns 422.
Example Prompts
Here are some example prompts you can use with Claude Code:
Check Authentication
Check my PostProxy authentication statusList Profiles
Show me all my available social media profilesPublish a Post
Using profile IDs:
Publish this post: "Check out our new product!" to profiles ["profile-123"]Using platform names:
Publish "Exciting news!" to linkedin and twitterInstagram Reel Audio and Collaboration Invites
Tool | Description |
| Search Meta's music / original-sound library (trending when no |
| List incoming collab invites (paginate with |
| Accept or decline an invite by |
These only work for Instagram profiles connected through Facebook Login (profile_groups_initialize_connection with onboarding: "facebook"); Instagram Login profiles return 422.
Pinterest Boards
Tool | Description |
| Create a board ( |
| Delete a board by |
YouTube Playlists
Tool | Description |
| List the channel's playlists (50 per page, |
| Create a playlist ( |
| Update |
| Delete a playlist (its videos stay on the channel) |
Pass a playlist's id as platforms.youtube.playlist_id in post_publish to add the uploaded video to it. Create/update/delete cost 50 YouTube API quota units each.
Publish with Platform Parameters
You can use platform-specific parameters to customize posts for each platform. The platforms parameter accepts an object where keys are platform names and values contain platform-specific options.
Instagram Examples
Regular Post with Collaborators:
Publish to Instagram: "Amazing content!" to my Instagram account with collaborators username1 and username2Or with explicit parameters:
{
"content": "Amazing content!",
"profiles": ["instagram"],
"media": ["https://example.com/image.jpg"],
"platforms": {
"instagram": {
"format": "post",
"collaborators": ["username1", "username2"],
"first_comment": "What do you think? 🔥"
}
}
}Instagram Reel:
{
"content": "Check out this reel! #viral",
"profiles": ["instagram"],
"media": ["https://example.com/video.mp4"],
"platforms": {
"instagram": {
"format": "reel",
"collaborators": ["collaborator_username"],
"cover_url": "https://example.com/thumbnail.jpg",
"audio_name": "Trending Audio",
"first_comment": "Link in bio!"
}
}
}Instagram Reel with Library Music (Facebook Login profiles; get audio_id from instagram_available_audio):
{
"content": "Summer vibes ☀️",
"profiles": ["instagram"],
"media": ["https://example.com/video.mp4"],
"platforms": {
"instagram": {
"format": "reel",
"audio_id": "1234567890123456",
"audio_volume": 80,
"strip_audio": true
}
}
}audio_volume / video_volume take 1–100 (default 100). strip_audio removes the video's own sound (reels and video stories) and works on any Instagram profile.
Instagram Story:
{
"profiles": ["instagram"],
"media": ["https://example.com/story-image.jpg"],
"platforms": {
"instagram": {
"format": "story"
}
}
}YouTube Examples
YouTube Video with Title and Privacy:
Upload this video to YouTube with title "My Tutorial" and make it publicOr with explicit parameters:
{
"content": "This is the video description with links and details",
"profiles": ["youtube"],
"media": ["https://example.com/video.mp4"],
"platforms": {
"youtube": {
"title": "My Tutorial: How to Build an API",
"privacy_status": "public",
"cover_url": "https://example.com/custom-thumbnail.jpg"
}
}
}Unlisted YouTube Video:
{
"content": "Video description",
"profiles": ["youtube"],
"media": ["https://example.com/video.mp4"],
"platforms": {
"youtube": {
"title": "Private Tutorial",
"privacy_status": "unlisted"
}
}
}TikTok Examples
Public TikTok with Auto Music:
{
"content": "Check this out! #fyp",
"profiles": ["tiktok"],
"media": ["https://example.com/video.mp4"],
"platforms": {
"tiktok": {
"privacy_status": "PUBLIC_TO_EVERYONE",
"auto_add_music": true,
"disable_comment": false,
"disable_duet": false,
"disable_stitch": false
}
}
}TikTok for Followers Only with AI Label:
{
"content": "Special content for followers",
"profiles": ["tiktok"],
"media": ["https://example.com/video.mp4"],
"platforms": {
"tiktok": {
"privacy_status": "FOLLOWER_OF_CREATOR",
"made_with_ai": true,
"brand_content_toggle": false
}
}
}Facebook Examples
Facebook Post with First Comment:
{
"content": "Check out our new product!",
"profiles": ["facebook"],
"media": ["https://example.com/product.jpg"],
"platforms": {
"facebook": {
"format": "post",
"first_comment": "Link to purchase: https://example.com/shop"
}
}
}Facebook Story:
{
"profiles": ["facebook"],
"media": ["https://example.com/story-video.mp4"],
"platforms": {
"facebook": {
"format": "story"
}
}
}Facebook Page Post:
{
"content": "Company announcement",
"profiles": ["facebook"],
"platforms": {
"facebook": {
"page_id": "123456789",
"first_comment": "Visit our website for more details"
}
}
}LinkedIn Examples
Personal LinkedIn Post:
{
"content": "Excited to share my latest article on AI",
"profiles": ["linkedin"],
"media": ["https://example.com/article-cover.jpg"]
}Company LinkedIn Post:
{
"content": "We're hiring! Join our team",
"profiles": ["linkedin"],
"media": ["https://example.com/careers.jpg"],
"platforms": {
"linkedin": {
"organization_id": "company-id-12345"
}
}
}Bluesky Examples
Plain Bluesky post (auto-faceted mentions/tags/links):
{
"content": "Hey @jay.bsky.team — check out our latest #ruby post: https://example.com/blog/post",
"profiles": ["bluesky"]
}You don't need any markup — Postproxy auto-converts @handles, #tags, and URLs into AT Protocol facets, and generates a link card preview from the URL's Open Graph meta (when no media is attached). 300-grapheme limit.
Telegram Examples
Telegram channel post (HTML formatting):
{
"content": "<b>New release</b> — read more on our blog https://example.com/post",
"profiles": ["telegram"],
"platforms": {
"telegram": {
"chat_id": "-1001234567890",
"parse_mode": "HTML",
"disable_link_preview": true,
"disable_notification": false
}
}
}Use profiles_placements against your Telegram profile to list channel chat_ids the bot can post to. The bot must be added to the channel as administrator with permission to post.
Cross-Platform Examples
Same Content, Different Platforms:
{
"content": "New product launch! 🚀",
"profiles": ["instagram", "twitter", "linkedin"],
"media": ["https://example.com/product.jpg"]
}Video Across Platforms with Specific Parameters:
{
"content": "Product launch video",
"profiles": ["instagram", "youtube", "tiktok"],
"media": ["https://example.com/video.mp4"],
"platforms": {
"instagram": {
"format": "reel",
"first_comment": "Link in bio!"
},
"youtube": {
"title": "Product Launch 2024",
"privacy_status": "public",
"cover_url": "https://example.com/yt-thumbnail.jpg"
},
"tiktok": {
"privacy_status": "PUBLIC_TO_EVERYONE",
"auto_add_music": true
}
}
}Platform Parameters Reference
Instagram:
format: "post" | "reel" | "story"collaborators: Array of usernames (max 10 for posts, 3 for reels)first_comment: String - comment to add after postingcover_url: String - thumbnail URL for reelsaudio_name: String - audio track name for reelstrial_strategy: "MANUAL" | "SS_PERFORMANCE" - trial strategy for reelsthumb_offset: String - thumbnail offset in milliseconds for reelsalt_text: String or array (matching media order) - image alt text, max 1,000 charsshare_to_feed: Boolean - reels only;falsepublishes to the Reels tab only (default shares to the feed/grid)disable_comment: Boolean - turn comments off right after publishing (posts, reels)location_id: String - numeric ID of a Facebook Page with an address to tag as the location (posts, reels; not stories)user_tags: Array of{ username, x, y, media_index }- tag public Instagram accounts on any format (post, reel, story). Images requirexandy(floats0.0–1.0from the top-left corner); reels and video slides are tagged by username only (coordinates are dropped); stories accept coordinates but don't need them.media_indexpicks the carousel slide (0-based, default0). A leading@is stripped. Out-of-range coordinates, amedia_indexpast the last media item, or an image tag missingx/yare rejected with a 422 naming the entry. Private accounts and accounts with tagging off are silently skipped by Instagram.
YouTube:
title: String - video titleprivacy_status: "public" | "unlisted" | "private"cover_url: String - custom thumbnail URLplaylist_id: String - add the video to this playlist (fromyoutube_playlists_list)
TikTok:
privacy_status: "PUBLIC_TO_EVERYONE" | "MUTUAL_FOLLOW_FRIENDS" | "FOLLOWER_OF_CREATOR" | "SELF_ONLY"photo_cover_index: Integer - index of photo to use as cover (0-based)auto_add_music: Boolean - enable automatic musicmade_with_ai: Boolean - mark content as AI-generateddisable_comment: Boolean - disable commentsdisable_duet: Boolean - disable duetsdisable_stitch: Boolean - disable stitchesbrand_content_toggle: Boolean - mark as paid partnership (third-party)brand_organic_toggle: Boolean - mark as paid partnership (own brand)upload_as_draft: Boolean - send to the creator's TikTok inbox instead of publishingthumb_offset: String - video cover frame in milliseconds
Facebook:
format: "post" | "story"first_comment: String - comment to add after postingpage_id: String - page ID for posting to company pageslink: String - URL shared as a link post with preview card (text-only)alt_text: String or array - image alt textmade_with_ai: Boolean - AI disclosure (photo posts only)countries: Array or comma-separated string - ISO country codes to restrict viewers to
LinkedIn:
format: "post" | "poll"organization_id: String - organization ID for company page postsreshare_urn: String - reshare an existing LinkedIn postalt_text: String or array - image alt textcountries: Array or comma-separated string - country targeting (organization posts only, up to 25)poll_question/poll_options/poll_duration_days: poll format — question 1-140 chars, 2-4 options of ≤30 chars, duration 1/3/7/14 daysdocument_title: String - title shown above an attached document (defaults to the file name)first_comment: String - comment posted right after publishing as the same author (max 1,250 chars; profiles connected on/after 2026-10-28)
Pinterest:
board_id: String - board placement fromprofiles_placements(create one withpinterest_board_create)title: String - pin title, max 100 charsdestination_link: String - URL the pin links tocover_url: String - cover image for video pinsthumb_offset: Integer - video thumbnail offset in secondsalt_text: String - image pin alt text
Telegram:
chat_id: String, required — destination channel/chat ID (useprofiles_placementsto list)parse_mode: "HTML" | "MarkdownV2" — omit for plain textdisable_link_preview: Boolean — suppress URL preview carddisable_notification: Boolean — send silently (no notification sound)Character limit: 4,096 for text-only; 1,024 for the caption when media is attached (body beyond is truncated)
Media: images ≤10 MB (×10), video ≤50 MB (×10), documents ≤50 MB (×1)
The bot must be a member (preferably administrator with post permission) of the destination channel
Bluesky:
alt_text: String or array - image alt textCharacter limit: 300 graphemes (emoji and combining sequences count as one)
Auto-detects
@handle.bsky.socialmentions,#hashtags, and URLs and converts them to clickable facetsGenerates a link card preview from Open Graph meta when a URL is present and no media is attached
Media: images ≤1 MB (×4), video ≤100 MB (×1, 1–60s)
Supports threads via the standard
threadarray
Twitter/X:
format: "post" | "poll"alt_text: String or array - image alt text, max 1,000 charspoll_options/poll_duration_minutes: poll format — 2-4 options of ≤25 chars, 5-10080 minutes
Threads:
alt_text: String or array - image alt texttopic_tag: String - one topic tag without#, max 50 chars, no periods or ampersands
For complete documentation, see the Platform Parameters Reference.
Create a Draft Post
Create a draft post: "Review this before publishing" to linkedinPublish a Draft Post
Publish draft post job-123Check Post Status
What's the status of job job-123?This will show detailed status including draft status, platform-specific errors, and publishing results.
Delete a Post
Delete post job-123Get Post Stats
Show me the stats for post abc123Get stats for posts abc123 and def456 filtered to Instagram only, from February 1st to todayList Placements
Show me the placements for my LinkedIn profile prof123Queue Management
Show me all my posting queuesCreate a queue called "Weekday Mornings" for profile group pg123, timezone America/New_York, with timeslots Monday through Friday at 9amAdd a post to queue q1abc with high priority: "Check out our latest feature!"Pause queue q1abcWhat's the next available slot for queue q1abc?Comment Management
Show me the comments on post abc123 for my Instagram profile prof456Reply to comment cmt_abc123 on post abc123 with "Thanks for the feedback!" using profile prof456Hide comment cmt_abc123 on post abc123 for profile prof456Direct Messages
List the DM chats for my Instagram profile prof456Reply "Yes, we ship worldwide!" in chat chat_xyz789Send a DM to the author of comment cmt_abc123 on post abc123 from profile prof456 saying "DM-ing you the details"Open a WhatsApp chat with +1 310 555 0007 on number 1055512345 of profile prof_wa and send the order_update template in en_US with Ana and ORD-12345Mark chat chat_wa1 as read and react to the last inbound message with 🔥WhatsApp Business Management
List the approved WhatsApp templates on profile prof_waCreate a UTILITY template called appointment_reminder in en_US on profile prof_wa: "Hi {{1}}, your appointment is on {{2}} at {{3}}."Show the quality rating and messaging tier for number 1055512345 on profile prof_waUpdate the WhatsApp business profile of number 1055512345 on prof_wa: about "Open Mon–Sat 9–18", website https://acme.exampleBlock +1 310 555 0099 on number 1055512345 of profile prof_waReport a Purchase of 49.90 USD for chat chat_wa1 on profile prof_wa with event id ord-9921View History
Show me the last 5 posts I publishedTroubleshooting
Server Won't Start
Check API Key: Ensure
POSTPROXY_API_KEYis set when registering withclaude mcp addCheck Node Version: Requires Node.js >= 18.0.0
Check Installation: Verify
postproxy-mcpis installed and in PATHCheck Registration: Ensure the server is registered via
claude mcp addand configuration is saved in~/.claude/plugins/
Authentication Errors
AUTH_MISSING: API key is not configured. Make sure you included
--env POSTPROXY_API_KEY=...when runningclaude mcp addAUTH_INVALID: API key is invalid. Verify your API key is correct.
Validation Errors
TARGET_NOT_FOUND: One or more profile IDs don't exist. Use
profiles_listto see available profiles.VALIDATION_ERROR: Post content or parameters are invalid. The API now returns detailed error messages:
400 errors:
{"status":400,"error":"Bad Request","message":"..."}422 errors:
{"errors": ["Error 1", "Error 2"]}- Array of validation error messagesCheck the error message for specific validation issues
API Errors
API_ERROR: Postproxy API returned an error. Check the error message for details.
Timeout: Request took longer than 30 seconds. Check your network connection and API status.
Platform Errors
When checking post status with post_status, platform-specific errors are now available in the error field of each platform object:
error: null- Post published successfullyerror: "Error message"- Detailed error message from the platform APICommon errors include authentication issues, rate limits, content violations, etc.
Draft Post Issues
If you create a draft post (draft: true) but receive draft: false in the response:
The response will include a
warningfield explaining that the API may have ignored the draft parameterThis can happen if:
The API does not support drafts with media attachments
The API has specific limitations for draft posts under certain conditions
Check the
warningfield in the response for detailsEnable debug mode (
POSTPROXY_MCP_DEBUG=1) to see detailed logging about draft parameter handling
Debug Mode
Enable debug logging by setting POSTPROXY_MCP_DEBUG=1 when registering the server:
claude mcp add --transport stdio postproxy-mcp --env POSTPROXY_API_KEY=your-api-key --env POSTPROXY_BASE_URL=https://api.postproxy.dev/api --env POSTPROXY_MCP_DEBUG=1 -- postproxy-mcpDevelopment
Building from Source
git clone https://github.com/postproxy/postproxy-mcp
cd postproxy-mcp
npm install
npm run buildRunning in Development Mode
npm run devLicense
MIT
Available Tools
44 toolsauth_statusARead-onlyInspect
Check authentication status, API configuration, and workspace information
Inputs: no named parameters.
comments_createAInspect
Create a comment or reply on a published post. The comment is published to the platform asynchronously. Supported on Instagram, Facebook, Threads, YouTube, and LinkedIn.
Inputs: text (required), post_id (required), profile_id (required), parent_id.
comments_deleteADestructiveIdempotentInspect
Delete a comment from the platform asynchronously. Supported on Instagram, Facebook, YouTube, and LinkedIn. Not supported on Threads.
Inputs: post_id (required), comment_id (required), profile_id (required).
comments_getARead-onlyInspect
Get a single comment with its replies
Inputs: post_id (required), comment_id (required), profile_id (required).
comments_hideADestructiveIdempotentInspect
Hide a comment on the platform asynchronously. Supported on Instagram, Facebook, and Threads.
Inputs: post_id (required), comment_id (required), profile_id (required).
comments_likeAIdempotentInspect
Like a comment on the platform asynchronously. Currently only supported on Facebook.
Inputs: post_id (required), comment_id (required), profile_id (required).
comments_listARead-onlyInspect
List comments on a published post. Returns paginated top-level comments with nested replies. Not all platforms support comments.
Inputs: post_id (required), profile_id (required), page, per_page.
comments_unhideAIdempotentInspect
Unhide a previously hidden comment on the platform asynchronously. Supported on Instagram, Facebook, and Threads.
Inputs: post_id (required), comment_id (required), profile_id (required).
comments_unlikeAIdempotentInspect
Remove a like from a comment on the platform asynchronously. Currently only supported on Facebook.
Inputs: post_id (required), comment_id (required), profile_id (required).
dm_chat_archiveAIdempotentInspect
Archive (mute) a chat. Bluesky only — calls Bluesky's muteConvo. Returns the chat with archived: true.
Inputs: chat_id (required).
dm_chat_createAIdempotentInspect
Find or create a chat for a participant on a DM-capable profile (idempotent — returns the existing chat if one already exists). Use before sending a message to a participant the profile has not yet messaged.
Inputs: profile_id (required), participant_external_id (required), participant_name, participant_username.
dm_chat_getARead-onlyIdempotentInspect
Get a single chat by Postproxy hashid or by the platform's external_conversation_id.
Inputs: chat_id (required).
dm_chats_listARead-onlyIdempotentInspect
List direct-message chats (conversations) for a DM-capable profile, ordered by most recent activity. Supported on Facebook (Messenger), Instagram, Telegram, and Bluesky.
Inputs: profile_id (required), page, after, before, +1 more.
dm_chat_unarchiveAIdempotentInspect
Unarchive (unmute) a chat. Bluesky only — calls Bluesky's unmuteConvo. Returns the chat with archived: false.
Inputs: chat_id (required).
dm_comment_private_replyAInspect
Send a DM to the author of a comment, in reply to that comment (Meta 'Private Replies'). Bypasses the 24h window (comments up to 7 days old) and creates/reuses a chat automatically. One private reply per comment, ever. Instagram and Facebook (Page comments) only.
Inputs: text (required), post_id (required), comment_id (required), profile_id (required).
dm_message_editADestructiveInspect
Edit a previously-sent outbound message on the platform. Telegram only — Facebook and Instagram do not expose outbound edits. Provide body (new text/caption) and/or reply_markup (pass {} to clear the keyboard); at least one is required.
Inputs: message_id (required), body, reply_markup.
dm_message_getBRead-onlyIdempotentInspect
Get a single message by Postproxy hashid or by the platform's external_id.
Inputs: message_id (required).
dm_message_reactAIdempotentInspect
Add a reaction from your business account to a message. Facebook Messenger and Instagram Direct only (not Telegram or Bluesky). A second react replaces the previous one.
Inputs: message_id (required), emoji, reaction.
dm_message_sendAInspect
Send an outbound direct message. Provide EITHER body (text) OR media (a single attachment), not both. The message is queued and delivered asynchronously (returns status: pending). Outside Meta's 24h messaging window, pass tag: HUMAN_AGENT (Facebook/Instagram only). reply_to_external_id and reply_markup are Telegram-only.
Inputs: chat_id (required), tag, body, media, +2 more.
dm_messages_listARead-onlyIdempotentInspect
List messages in a chat, most recent first. Optionally filter by direction or status.
Inputs: chat_id (required), page, status, per_page, +1 more.
dm_message_unreactAIdempotentInspect
Remove your business account's reaction from a message. Facebook Messenger and Instagram Direct only.
Inputs: message_id (required).
history_listBRead-onlyInspect
List recent post jobs
Inputs: limit.
post_deleteADestructiveIdempotentInspect
Delete a post from the database. By default does NOT remove from social media platforms. Pass delete_on_platform=true to also remove from all published platforms before DB deletion.
Inputs: post_id (required), delete_on_platform.
post_delete_on_platformADestructiveInspect
Delete a published post from social media platforms WITHOUT removing it from the database. Async via background job. Optionally narrow scope by post_profile_id (covers entire thread for that profile), profile_id, or network. With no scope, deletes from all published platforms. Supported: Facebook, Threads, X (Twitter), LinkedIn, Pinterest, YouTube. NOT supported: Instagram, TikTok.
Inputs: post_id (required), network, profile_id, post_profile_id.
post_publishAInspect
Publish a post to specified social media profiles. Supports text content, media attachments, scheduling, drafts, threads (X and Threads only), and platform-specific customization via the 'platforms' parameter.
Inputs: content (required), profiles (required), draft, media, +7 more.
post_publish_draftAInspect
Publish a draft post. Only posts with draft status can be published using this endpoint
Inputs: post_id (required).
post_statsARead-onlyInspect
Get stats snapshots for one or more posts. Returns all matching snapshots so you can see trends over time. Supports filtering by profiles/networks and timespan.
Inputs: post_ids (required), to, from, profiles.
post_statusARead-onlyInspect
Get status of a published post by post ID
Inputs: post_id (required).
post_updateADestructiveInspect
Update an existing post. Only drafts or scheduled posts (more than 5 min before publish) can be updated. Only send fields you want to change — omitted fields are left unchanged.
Inputs: post_id (required), draft, media, thread, +6 more.
profile_comments_createAInspect
Reply to an existing profile comment (Google Business review). Top-level comments are NOT allowed — you can only reply to a review that already exists. parent_id is required. Response is returned immediately with status 'pending'; a background job then publishes to Google and updates status to 'published' or 'failed'.
Inputs: text (required), parent_id (required), profile_id (required).
profile_comments_deleteADestructiveIdempotentInspect
Delete your reply to a profile comment. Only your own reply is removed — the underlying review is NOT deleted (Google does not allow businesses to delete reviews). Returns {accepted: true} while the delete is dispatched asynchronously.
Inputs: comment_id (required), profile_id (required).
profile_comments_getARead-onlyInspect
Get a single profile comment (review or your reply) by Postproxy hashid or the platform's external_id (e.g. 'accounts/.../locations/.../reviews/...').
Inputs: comment_id (required), profile_id (required).
profile_comments_listARead-onlyInspect
List profile-scoped comments. Currently surfaces Google Business reviews (reviews live on a location, not a post, so they cannot be reached via comments_list). Each item may include nested replies. Reviews sync from Google twice daily (06:00 and 18:00 UTC).
Inputs: profile_id (required), page, per_page, placement_id.
profile_groups_listARead-onlyIdempotentInspect
List all profile groups accessible with your API key. Profile groups are organizational containers (e.g. per brand or client) that hold related social media profiles. Use the returned group id to filter profiles_list by profile_group_id.
Inputs: no named parameters.
profiles_listARead-onlyInspect
List all available social media profiles for posting. Optionally filter by profile_group_id.
Inputs: profile_group_id.
profiles_placementsARead-onlyInspect
List available placements for a profile. For Facebook: business pages. For LinkedIn: personal profile and organizations. For Pinterest: boards. For Telegram: channels the bot can post to. For Google Business: locations (returned as full resource paths 'accounts/X/locations/Y' to pass as location_id). Available for facebook, linkedin, pinterest, telegram, and google_business profiles.
Inputs: profile_id (required).
profiles_statsARead-onlyInspect
Get the follower/engagement timeseries for a profile. Returns daily snapshots (captured every ~23h). placement_id is required for facebook, linkedin, and telegram profiles (get it from profiles_placements); omit for other networks. Fields in records[].stats are platform-native and not normalized.
Inputs: profile_id (required), to, from, placement_id.
queues_createAInspect
Create a new posting queue with weekly timeslots. Use profiles.list to find the profile_group_id.
Inputs: name (required), profile_group_id (required), jitter, timezone, +2 more.
queues_deleteADestructiveIdempotentInspect
Delete a posting queue. Posts in the queue will have their queue reference removed but will not be deleted.
Inputs: queue_id (required).
queues_getARead-onlyInspect
Get details of a single posting queue including its timeslots and post count
Inputs: queue_id (required).
queues_listARead-onlyInspect
List all posting queues. Queues automatically schedule posts into recurring weekly timeslots with priority-based ordering.
Inputs: profile_group_id.
queues_next_slotARead-onlyInspect
Get the next available timeslot for a queue
Inputs: queue_id (required).
queues_updateADestructiveInspect
Update a queue's settings, timeslots, or pause/unpause it. Changes to timezone or timeslots trigger rearrangement of all queued posts.
Inputs: queue_id (required), name, jitter, enabled, +3 more.
upload_createAInspect
Create a temporary file upload URL for sandboxed environments. Returns a key, an upload_url, and expires_in (seconds). Flow: (1) call this tool, (2) POST the raw file bytes to the returned upload_url (valid for expires_in seconds), which responds with {"url": "https://..."}, (3) pass that returned url in the media array of post_publish (or post_update). The upload host is tmpfiles.postproxy.dev — that domain must be whitelisted/allowlisted in the sandbox's network egress rules for the upload to succeed. Only use this when running against the remote (hosted) MCP server: if you are running the local (stdio) MCP server, do NOT use this — instead pass local file paths directly in the media array, which uploads them via multipart.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 44 tools
Each tool targets a distinct action and context, clearly differentiated by prefixes (e.g., comments_ vs dm_ vs post_) and specific verbs. No two tools appear to do the same thing, even among similar operations like comments_create and profile_comments_create.
All tool names follow a consistent '[domain]_[action]' pattern in snake_case, with clear prefixes for each functional area (comments, dm, post, profile, queue, etc.). The naming is predictable and uniform across the entire set.
44 tools is on the high side for typical MCP servers, but the broad scope (multiple social networks, posts, comments, DMs, profiles, queues) justifies many of them. A few tools could potentially be combined without loss of clarity, but overall the count is borderline heavy rather than excessive.
The tool surface covers the major lifecycle operations for social media management: publishing, comments, direct messages, profiles, and queues. Notable but minor gaps exist, such as lack of a direct 'get post by ID' tool (only status and history) and no media library management. Overall, agents can accomplish core workflows.
Maintenance
Related MCP Connectors
Lets Claude and AI agents post and schedule on Instagram, TikTok, LinkedIn and 5 more networks.
Run social media from Claude: draft, schedule and approve posts, answer comments, read results.
Schedule and publish social media posts from Claude, ChatGPT or any AI agent to 8 networks.
Schedule and publish to all your social channels from Claude, ChatGPT and other AI apps
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables generating, scheduling, and publishing social media posts via Claude or an agent through the MCP protocol.13 npmMIT
- FlicenseAqualityCmaintenanceSchedule and manage social media posts across Facebook, Instagram, Twitter/X, LinkedIn, YouTube, TikTok, and Pinterest directly from Claude.10-
- AlicenseNot gradedqualityCmaintenanceAutomate Aidelly social media management directly from Claude Code. Create, schedule, and manage posts across all connected platforms with AI-powered MCP tools.MIT
- AlicenseAqualityCmaintenanceEnables Claude to list platform login status and rules, preview posts, and publish text, images, or video to X, LinkedIn, YouTube, Facebook Pages, Instagram, and TikTok from one MCP interface. Each post is validated against per-platform rules before publishing, which requires explicit confirmation.3MIT