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.

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

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 job ID
`post.publish_draft`	Publish a draft post
`post.delete`	Delete a post by job ID
`post.stats`	Get stats snapshots for one or more posts
`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.

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
`media`	string[]	No	-	Array of media URLs or local file paths
`idempotency_key`	string	No	-	Idempotency key for deduplication
`require_confirmation`	boolean	No	`false`	If true, return summary without publishing
`draft`	boolean	No	`false`	If true, creates a draft post that won’t publish automatically
`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

{
"job_id": "job-123",
"accepted_at": "2024-01-01T12:00:00Z",
"status": "pending",
"draft": true
}

Response fields

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

`post.status`

Get status of a published post by job ID.

Parameters

Name	Type	Required	Description
`job_id`	string	Yes	Job ID from post.publish response

Response

{
"job_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
`job_id`	string	Job identifier
`overall_status`	string	Overall status: `draft`, `pending`, `processing`, `complete`, `failed`
`draft`	boolean	Whether the post is a draft
`status`	string	Job status: `pending`, `processed`, `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

`post.delete`

Delete a post by job ID.

Parameters

Name	Type	Required	Description
`job_id`	string	Yes	Job ID to delete

Response

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

Response fields

Field	Type	Description
`job_id`	string	Job 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
`job_id`	string	Yes	Job ID of the draft post to publish

Response

{
"job_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
`job_id`	string	Job identifier
`status`	string	Job 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 job 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": [
  {
    "job_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[].job_id`	string	Unique job 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

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
`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)
`auto_add_music`	boolean	Enable automatic music
`made_with_ai`	boolean	Mark content as AI-generated
`disable_comment`	boolean	Disable comments
`disable_duet`	boolean	Disable duets
`disable_stitch`	boolean	Disable stitches
`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"` or `"story"`
`first_comment`	string	Comment to add after posting
`page_id`	string	Page ID for posting to company 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 job 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

Delete a Post

Delete post job-123

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