MCP Server

The PostProxy MCP Server provides tools for publishing posts, checking statuses, and managing social media profiles 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
`post.publish`	Publish a post to specified targets
`post.status`	Get status of a published post by job ID
`post.delete`	Delete a post by job ID
`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

Post Management

`post.publish`

Publish a post to specified targets.

Parameters

Name	Type	Required	Default	Description
`content`	string	Yes	-	Post content text
`targets`	string[]	Yes	-	Array of target profile IDs (must belong to same profile group)
`schedule`	string	No	-	ISO 8601 scheduled time
`media`	string[]	No	-	Array of media URLs
`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

Response

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

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`

`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",
"platforms": [
  {
    "platform": "twitter",
    "status": "ok",
    "url": "https://twitter.com/status/123",
    "post_id": "123"
  }
]
}

Response fields

Field	Type	Description
`job_id`	string	Job identifier
`overall_status`	string	Overall status: `pending`, `processing`, `complete`, `failed`
`platforms`	array	Array of platform-specific posting results
`platforms[].platform`	string	Platform identifier
`platforms[].status`	string	Platform posting status: `ok`, `failed`, `pending`
`platforms[].url`	string\|null	URL of the published post (if available)
`platforms[].post_id`	string\|null	Platform-specific post ID (if available)

`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

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",
    "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[].platforms_count`	integer	Number of platforms the post was published to

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

Publish this post: "Check out our new product!" to accounts ["profile-123"]

Check Post Status

What's the status of job job-123?

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 target profile IDs don’t exist. Use profiles.list to see available targets.
VALIDATION_ERROR: Post content or parameters are invalid. Check error messages for details.

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.

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