MCP Server

The Postproxy MCP Server provides tools for publishing posts, checking statuses, managing social media profiles, and retrieving post statistics through Claude Code. This server implements the Model Context Protocol (MCP) to enable seamless integration between Postproxy and Claude Code.

You can use Postproxy’s hosted remote MCP (no install) or run the postproxy-mcp npm package locally with stdio transport—both expose the same tools.

Remote MCP

Postproxy runs the MCP server for you at a public HTTPS endpoint. Point your client at that URL and authenticate with your API key. You skip installing Node, postproxy-mcp, and maintaining a local stdio process.

Claude Code

claude mcp add --transport http postproxy \
https://mcp.postproxy.dev/mcp?api_key=YOUR_KEY

Replace YOUR_KEY with your Postproxy API key.

Authentication

Query parameter: append api_key=YOUR_KEY to the MCP URL (as in the example above).
Header: alternatively, many clients can send X-Postproxy-API-Key: YOUR_KEY instead of putting the key in the URL.

Use whichever method your MCP client supports.

After connecting

Restart your Claude Code session if the client requires it.
Test with a prompt such as: “Check my Postproxy authentication status.”
If the Postproxy tools appear, you can publish and manage posts the same way as with the local server.

Installation

Global Installation

Install the MCP server globally using npm:

npm install -g postproxy-mcp

Local Installation

Install the MCP server locally in your project:

npm install postproxy-mcp

Claude Code stores MCP server configuration under ~/.claude/plugins/. After installing postproxy-mcp, Claude will automatically detect the server on restart.

Configuration

The steps below apply to the local postproxy-mcp package (stdio transport). If you use the hosted remote MCP instead, you only need the HTTP URL and API key—no npm install or env vars on your machine.

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-mcp

Replace 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:

Command
Alternative

postproxy-mcp setup

postproxy-mcp-setup

This will guide you through the setup process step by step and register the server using claude mcp add automatically.

Available Tools

The MCP server provides the following tools for interacting with Postproxy:

Tool	Description
`auth_status`	Check authentication status and API configuration
`profiles_list`	List all available social media profiles
`profiles_placements`	List available placements for a profile (Facebook pages, LinkedIn orgs, Pinterest boards)
`post_publish`	Publish a post to specified profiles
`post_status`	Get status of a published post by post ID
`post_update`	Update an existing draft or scheduled post
`post_publish_draft`	Publish a draft post
`post_delete`	Delete a post by post ID
`post_stats`	Get stats snapshots for one or more posts
`queues_list`	List all posting queues
`queues_get`	Get details of a single posting queue
`queues_create`	Create a new posting queue with weekly timeslots
`queues_update`	Update a queue’s settings, timeslots, or pause/unpause it
`queues_delete`	Delete a posting queue
`queues_next_slot`	Get the next available timeslot for a queue
`comments_list`	List comments on a published post
`comments_get`	Get a single comment with its replies
`comments_create`	Create a comment or reply on a published post
`comments_delete`	Delete a comment from the platform
`comments_hide`	Hide a comment on the platform
`comments_unhide`	Unhide a previously hidden comment
`comments_like`	Like a comment on the platform
`comments_unlike`	Remove a like from a comment
`history_list`	List recent post jobs

Authentication Tools

`auth_status`

Check authentication status, API configuration, and workspace information.

Parameters

Name	Type	Required	Description
None	-	-	This tool requires no parameters

Response

{
"authenticated": true,
"base_url": "https://api.postproxy.dev/api",
"profile_groups_count": 2
}

Response fields

Field	Type	Description
`authenticated`	boolean	Whether the API key is valid and authenticated
`base_url`	string	Base URL of the Postproxy API
`profile_groups_count`	integer	Number of profile groups in the account

Profile Management

`profiles_list`

List all available social media profiles (targets) for posting.

Parameters

Name	Type	Required	Description
None	-	-	This tool requires no parameters

Response

{
"targets": [
  {
    "id": "profile-123",
    "name": "My Twitter Account",
    "platform": "twitter",
    "profile_group_id": 1
  }
]
}

Response fields

Field	Type	Description
`targets`	array	Array of available profile objects
`targets[].id`	string	Unique profile identifier
`targets[].name`	string	Display name of the connected account
`targets[].platform`	string	Platform identifier (twitter, facebook, instagram, etc.)
`targets[].profile_group_id`	integer	ID of the profile group this profile belongs to

`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. Available for facebook, linkedin, and pinterest profiles.

Parameters

Name	Type	Required	Description
`profile_id`	string	Yes	Profile ID

Response (LinkedIn example)

{
"placements": [
  {
    "id": null,
    "name": "Personal Profile"
  },
  {
    "id": "108520199",
    "name": "Acme Marketing"
  }
]
}

Response fields

Field	Type	Description
`placements`	array	Array of placement objects
`placements[].id`	string\|null	Placement identifier (null for personal profiles)
`placements[].name`	string	Display name of the placement

Post Management

`post_publish`

Publish a post to specified social media profiles. Supports text content, media attachments, scheduling, drafts, threads (X and Threads only), and platform-specific customization.

Parameters

Name	Type	Required	Default	Description
`content`	string	Yes	-	Post content text
`profiles`	string[]	Yes	-	Array of profile IDs or platform names (e.g., `"linkedin"`, `"instagram"`, `"twitter"`). When using platform names, posts to the first connected profile for that platform.
`schedule`	string	No	-	ISO 8601 scheduled time. Do not use together with `queue_id`.
`media`	string[]	No	-	Array of media URLs or local file paths (absolute, relative, or `~/` paths)
`idempotency_key`	string	No	-	Idempotency key for deduplication
`require_confirmation`	boolean	No	`false`	If true, return summary without publishing (dry run)
`draft`	boolean	No	`false`	If true, creates a draft post that won’t publish automatically
`thread`	array	No	-	Array of thread child posts (X/Twitter and Threads only). Each item has `body` (string, required) and `media` (string[], optional). The parent post is published first, then each child is published as a reply in order.
`queue_id`	string	No	-	Queue ID to add the post to. The queue will automatically assign a timeslot. Do not use together with `schedule`.
`queue_priority`	string	No	`"medium"`	Priority when adding to a queue: `"high"`, `"medium"`, or `"low"`. Higher priority posts get earlier timeslots.
`platforms`	object	No	-	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.

Platform Parameters 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
}
}

Response

{
"post_id": "job-123",
"status": "pending",
"draft": true,
"scheduled_at": null,
"created_at": "2024-01-01T12:00:00Z"
}

Response fields

Field	Type	Description
`post_id`	string	Unique post identifier for tracking the post
`status`	string	Initial status of the post: `pending`, `processing`, `processed`
`draft`	boolean	Whether the post was created as a draft
`scheduled_at`	string\|null	ISO 8601 timestamp if scheduled
`created_at`	string	ISO 8601 timestamp when the post was created
`warning`	string\|null	Warning message if the API may have ignored the draft parameter

`post_status`

Get status of a published post by post ID.

Parameters

Name	Type	Required	Description
`post_id`	string	Yes	Post ID from post.publish response

Response

{
"post_id": "job-123",
"overall_status": "complete",
"draft": false,
"status": "processed",
"platforms": [
  {
    "platform": "twitter",
    "status": "published",
    "url": "https://twitter.com/status/123",
    "post_id": "123",
    "error": null,
    "attempted_at": "2024-01-01T12:00:00Z"
  }
]
}

Response fields

Field	Type	Description
`post_id`	string	Postproxy post identifier
`overall_status`	string	Overall status: `draft`, `pending`, `processing`, `complete`, `failed`, `media_processing_failed`
`draft`	boolean	Whether the post is a draft
`status`	string	Post status: `pending`, `processing`, `processed`, `draft`, `scheduled`, `media_processing_failed`
`platforms`	array	Array of platform-specific posting results
`platforms[].platform`	string	Platform identifier
`platforms[].status`	string	Platform posting status: `pending`, `processing`, `published`, `failed`, `deleted`
`platforms[].url`	string\|null	URL of the published post (if available)
`platforms[].post_id`	string\|null	Platform-specific post ID (if available)
`platforms[].error`	string\|null	Error message if publishing failed (null if successful)
`platforms[].attempted_at`	string	ISO 8601 timestamp when posting was attempted
`platforms[].insights`	object\|null	Platform-specific insights (if available)
`media`	array\|undefined	Array of media objects (only present if the post has media)
`thread`	array\|undefined	Array of thread child posts (only present if the post has thread children)

`post_update`

Update an existing post. Only drafts or scheduled posts (more than 5 minutes before publish) can be updated. Only send fields you want to change — omitted fields are left unchanged.

Parameters

Name	Type	Required	Default	Description
`post_id`	string	Yes	-	Post ID to update
`content`	string	No	-	Updated text content
`profiles`	string[]	No	-	Replace all profiles (array of profile IDs or platform names). Full replace — omit to keep existing.
`schedule`	string	No	-	Updated ISO 8601 scheduled time
`draft`	boolean	No	-	Set or unset draft status
`media`	string[]	No	-	Replace all media (array of media URLs). Full replace — send empty array to remove all. Omit to keep existing.
`platforms`	object	No	-	Platform-specific parameters (merged with existing). Same structure as `post_publish`.
`thread`	array	No	-	Replace all thread children (full replace). Send empty array to remove all. Omit to keep existing.
`queue_id`	string	No	-	Queue ID to assign the post to
`queue_priority`	string	No	-	Queue priority: `"high"`, `"medium"`, or `"low"`

Response

{
"post_id": "job-123",
"status": "draft",
"draft": true,
"scheduled_at": null,
"created_at": "2024-01-01T12:00:00Z",
"message": "Post updated successfully"
}

Response fields

Field	Type	Description
`post_id`	string	Post identifier
`status`	string	Post status after update
`draft`	boolean	Whether the post is a draft
`scheduled_at`	string\|null	ISO 8601 timestamp if scheduled
`created_at`	string	ISO 8601 timestamp when the post was created
`message`	string	Success message

`post_delete`

Delete a post by post ID.

Parameters

Name	Type	Required	Description
`post_id`	string	Yes	Post ID to delete

Response

{
"post_id": "job-123",
"deleted": true
}

Response fields

Field	Type	Description
`post_id`	string	Post identifier that was deleted
`deleted`	boolean	Whether the deletion was successful

`post_publish_draft`

Publish a draft post. Only posts with draft: true status can be published using this endpoint.

Parameters

Name	Type	Required	Description
`post_id`	string	Yes	Post ID of the draft post to publish

Response

{
"post_id": "job-123",
"status": "processed",
"draft": false,
"scheduled_at": null,
"created_at": "2024-01-01T12:00:00Z",
"message": "Draft post published successfully"
}

Response fields

Field	Type	Description
`post_id`	string	Post identifier
`status`	string	Post status after publishing
`draft`	boolean	Will be `false` after publishing
`scheduled_at`	string\|null	ISO 8601 timestamp if scheduled
`created_at`	string	ISO 8601 timestamp when the post was created
`message`	string	Success message

`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

Name	Type	Required	Default	Description
`post_ids`	string[]	Yes	-	Array of post IDs (max 50)
`profiles`	string	No	-	Comma-separated list of profile IDs or network names (e.g. `instagram,twitter` or `abc123,def456` or mixed)
`from`	string	No	-	ISO 8601 timestamp — only include snapshots recorded at or after this time
`to`	string	No	-	ISO 8601 timestamp — only include snapshots recorded at or before this time

Response

{
"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"
          }
        ]
      }
    ]
  }
}
}

Response fields

Field	Type	Description
`data`	object	Object keyed by post ID
`data[].platforms`	array	Array of platform-specific stats
`data[].platforms[].profile_id`	string	Profile identifier
`data[].platforms[].platform`	string	Platform name
`data[].platforms[].records`	array	Array of stat snapshots over time
`data[].platforms[].records[].stats`	object	Stats object (fields vary by platform)
`data[].platforms[].records[].recorded_at`	string	ISO 8601 timestamp when stats were recorded

Stats fields by platform

Platform	Available Fields
Instagram	`impressions`, `likes`, `comments`, `saved`, `profile_visits`, `follows`
Facebook	`impressions`, `clicks`, `likes`
Threads	`impressions`, `likes`, `replies`, `reposts`, `quotes`, `shares`
Twitter	`impressions`, `likes`, `retweets`, `comments`, `quotes`, `saved`
YouTube	`impressions`, `likes`, `comments`, `saved`
LinkedIn	`impressions`
TikTok	`impressions`, `likes`, `comments`, `shares`
Pinterest	`impressions`, `likes`, `comments`, `saved`, `outbound_clicks`

History

`history_list`

List recent post jobs.

Parameters

Name	Type	Required	Default	Description
`limit`	number	No	`10`	Maximum number of jobs to return

Response

{
"jobs": [
  {
    "post_id": "job-123",
    "content_preview": "Post content preview...",
    "created_at": "2024-01-01T12:00:00Z",
    "overall_status": "complete",
    "draft": false,
    "platforms_count": 2
  }
]
}

Response fields

Field	Type	Description
`jobs`	array	Array of job objects
`jobs[].post_id`	string	Unique post identifier
`jobs[].content_preview`	string	Preview of the post content
`jobs[].created_at`	string	ISO 8601 timestamp when the job was created
`jobs[].overall_status`	string	Overall status of the job
`jobs[].draft`	boolean	Whether the post is a draft
`jobs[].platforms_count`	integer	Number of platforms the post was published to

Queue Management

Queues automatically schedule posts into recurring weekly timeslots with priority-based ordering.

`queues_list`

List all posting queues.

Parameters

Name	Type	Required	Description
`profile_group_id`	string	No	Filter queues by profile group

Response

{
"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

Name	Type	Required	Description
`queue_id`	string	Yes	Queue ID

`queues_create`

Create a new posting queue with weekly timeslots.

Parameters

Name	Type	Required	Default	Description
`profile_group_id`	string	Yes	-	Profile group ID to connect the queue to (use `profiles_list` to find this)
`name`	string	Yes	-	Queue name
`description`	string	No	-	Optional description
`timezone`	string	No	`"UTC"`	IANA timezone name (e.g. `"America/New_York"`)
`jitter`	number	No	`0`	Random offset in minutes (0-60) applied to scheduled times for natural posting patterns
`timeslots`	array	No	-	Initial weekly timeslots. Each object has `day` (0=Sunday through 6=Saturday) and `time` (24-hour `HH:MM` format).

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

Name	Type	Required	Description
`queue_id`	string	Yes	Queue ID to update
`name`	string	No	New queue name
`description`	string	No	New description
`timezone`	string	No	IANA timezone name
`enabled`	boolean	No	Set to `false` to pause the queue, `true` to unpause
`jitter`	number	No	Random offset in minutes (0-60)
`timeslots`	array	No	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

Name	Type	Required	Description
`queue_id`	string	Yes	Queue ID to delete

`queues_next_slot`

Get the next available timeslot for a queue.

Parameters

Name	Type	Required	Description
`queue_id`	string	Yes	Queue ID

Response

{
"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 using the queue_id and queue_priority parameters:

{
"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

Name	Type	Required	Default	Description
`post_id`	string	Yes	-	Post ID
`profile_id`	string	Yes	-	Profile ID to identify which platform’s comments to retrieve
`page`	number	No	`0`	Page number, zero-indexed
`per_page`	number	No	`20`	Number of top-level comments per page

Response

{
"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"
      }
    ]
  }
]
}

`comments_get`

Get a single comment with its replies.

Parameters

Name	Type	Required	Description
`post_id`	string	Yes	Post ID
`comment_id`	string	Yes	Comment ID (Postproxy ID or platform external ID)
`profile_id`	string	Yes	Profile ID

`comments_create`

Create a comment or reply on a published post. The comment is published to the platform asynchronously.

Parameters

Name	Type	Required	Description
`post_id`	string	Yes	Post ID
`profile_id`	string	Yes	Profile ID
`text`	string	Yes	Comment text content
`parent_id`	string	No	ID of comment to reply to (Postproxy ID or external ID). Omit to comment on the post itself.

Response

{
"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

Name	Type	Required	Description
`post_id`	string	Yes	Post ID
`comment_id`	string	Yes	Comment ID (Postproxy ID or external ID)
`profile_id`	string	Yes	Profile ID

`comments_hide`

Hide a comment on the platform asynchronously. Supported on Instagram, Facebook, and Threads.

Parameters

Name	Type	Required	Description
`post_id`	string	Yes	Post ID
`comment_id`	string	Yes	Comment ID
`profile_id`	string	Yes	Profile ID

`comments_unhide`

Unhide a previously hidden comment. Supported on Instagram, Facebook, and Threads.

Parameters

Name	Type	Required	Description
`post_id`	string	Yes	Post ID
`comment_id`	string	Yes	Comment ID
`profile_id`	string	Yes	Profile ID

`comments_like`

Like a comment on the platform asynchronously. Currently only supported on Facebook.

Parameters

Name	Type	Required	Description
`post_id`	string	Yes	Post ID
`comment_id`	string	Yes	Comment ID
`profile_id`	string	Yes	Profile ID

`comments_unlike`

Remove a like from a comment. Currently only supported on Facebook.

Parameters

Name	Type	Required	Description
`post_id`	string	Yes	Post ID
`comment_id`	string	Yes	Comment ID
`profile_id`	string	Yes	Profile ID

Comment Platform Support

Action	Instagram	Facebook	Threads	YouTube	LinkedIn
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

Platform Parameters

The platforms parameter in post_publish allows you to specify platform-specific options for each social media platform. This enables advanced features like Instagram Reels, YouTube video titles, TikTok privacy settings, and more.

Instagram Parameters

Parameter	Type	Description
`format`	string	Post format: `"post"`, `"reel"`, or `"story"`
`collaborators`	string[]	Array of usernames (max 10 for posts, 3 for reels)
`first_comment`	string	Comment to add after posting
`cover_url`	string	Thumbnail URL for reels
`audio_name`	string	Audio track name for reels
`trial_strategy`	string	Trial strategy for reels: `"MANUAL"` or `"SS_PERFORMANCE"`
`thumb_offset`	string	Thumbnail offset in milliseconds for reels

Instagram Examples

{
"content": "Amazing content!",
"profiles": ["instagram"],
"media": ["https://example.com/image.jpg"],
"platforms": {
  "instagram": {
    "format": "post",
    "collaborators": ["username1", "username2"],
    "first_comment": "What do you think? 🔥"
  }
}
}

{
"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!"
  }
}
}

YouTube Parameters

Parameter	Type	Description
`title`	string	Video title
`privacy_status`	string	Privacy setting: `"public"`, `"unlisted"`, or `"private"`
`cover_url`	string	Custom thumbnail URL
`made_for_kids`	boolean	Mark content as made for kids

YouTube Examples

{
"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"
  }
}
}

TikTok Parameters

Parameter	Type	Description
`format`	string	Content format: `"video"` or `"image"`
`privacy_status`	string	Privacy setting: `"PUBLIC_TO_EVERYONE"`, `"MUTUAL_FOLLOW_FRIENDS"`, `"FOLLOWER_OF_CREATOR"`, or `"SELF_ONLY"`
`photo_cover_index`	integer	Index of photo to use as cover (0-based, image only)
`auto_add_music`	boolean	Enable automatic music (image only)
`made_with_ai`	boolean	Mark content as AI-generated (video only)
`disable_comment`	boolean	Disable comments
`disable_duet`	boolean	Disable duets (video only)
`disable_stitch`	boolean	Disable stitches (video only)
`brand_content_toggle`	boolean	Mark as paid partnership (third-party)
`brand_organic_toggle`	boolean	Mark as paid partnership (own brand)

TikTok Examples

{
"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
  }
}
}

Facebook Parameters

Parameter	Type	Description
`format`	string	Post format: `"post"`, `"story"`, or `"reel"`
`title`	string	Title for reels (reel format only)
`first_comment`	string	Comment to add after posting
`page_id`	string	Page ID for posting to company pages (use `profiles_placements` to get available pages)

Facebook Examples

{
"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"
  }
}
}

LinkedIn Parameters

Parameter	Type	Description
`organization_id`	string	Organization ID for company page posts

LinkedIn Examples

{
"content": "We're hiring! Join our team",
"profiles": ["linkedin"],
"media": ["https://example.com/careers.jpg"],
"platforms": {
  "linkedin": {
    "organization_id": "company-id-12345"
  }
}
}

Cross-Platform Example

{
"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
  }
}
}

For complete documentation, see the Platform Parameters Reference.

Example Prompts

Here are some example prompts you can use with Claude Code:

Check Authentication

Check my Postproxy authentication status

List Profiles

Show me all my available social media profiles

Publish 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 twitter

Create a Draft Post

Create a draft post: "Review this before publishing" to linkedin

Publish a Draft Post

Publish draft post job-123

Check Post Status

What's the status of post job-123?

This will show detailed status including draft status, platform-specific errors, and publishing results.

Get Post Stats

Show me the stats for post abc123

Get stats for posts abc123 and def456 filtered to Instagram only, from February 1st to today

List Placements

Show me the placements for my LinkedIn profile prof123

Update a Post

Update the content of draft post job-123 to "Updated content here"

Delete a Post

Delete post job-123

Queue Management

Show me all my posting queues

Create a queue called "Weekday Mornings" for profile group pg123, timezone America/New_York, with timeslots Monday through Friday at 9am

Add a post to queue q1abc with high priority: "Check out our latest feature!"

Pause queue q1abc

What's the next available slot for queue q1abc?

Comment Management

Show me the comments on post abc123 for my Instagram profile prof456

Reply to comment cmt_abc123 on post abc123 with "Thanks for the feedback!" using profile prof456

Hide comment cmt_abc123 on post abc123 for profile prof456

Publish a Thread

Publish a thread on Twitter: first post "Part 1: Introduction to our new feature", then "Part 2: Here's how it works", then "Part 3: Try it out today!"

View History

Show me the last 5 posts I published

Troubleshooting

Server Won’t Start

Check API Key: Ensure POSTPROXY_API_KEY is set when registering with claude mcp add
Check Node Version: Requires Node.js >= 18.0.0
Check Installation: Verify postproxy-mcp is installed and in PATH
Check Registration: Ensure the server is registered via claude mcp add and configuration is saved in ~/.claude/plugins/

Authentication Errors

AUTH_MISSING: API key is not configured. Make sure you included --env POSTPROXY_API_KEY=... when running claude mcp add
AUTH_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_list to 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 messages
- Check 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 successfully
error: "Error message" - Detailed error message from the platform API
Common 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 warning field explaining that the API may have ignored the draft parameter
This 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 warning field in the response for details
Enable 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-mcp