MCP Server

The @voxburst/mcp-server package lets AI assistants (Claude, Cursor, Windsurf, and others) manage your VoxBurst workspace through the Model Context Protocol (MCP) .

Installation

npm install -g @voxburst/mcp-server

Or run directly without installing:

npx @voxburst/mcp-server

Configuration

Environment Variables

Get your API key from VoxBurst Settings . Use a key with the scopes your agent needs (at minimum posts:write and accounts:read).

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "voxburst": {
      "command": "npx",
      "args": ["@voxburst/mcp-server"],
      "env": {
        "VOXBURST_API_KEY": "vb_live_xxxxxxxxxxxxx"
      }
    }
  }
}

Restart Claude Desktop after saving the config.

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json or the global MCP config):

{
  "mcpServers": {
    "voxburst": {
      "command": "npx",
      "args": ["@voxburst/mcp-server"],
      "env": {
        "VOXBURST_API_KEY": "vb_live_xxxxxxxxxxxxx"
      }
    }
  }
}

Windsurf / VS Code with MCP Extension

{
  "mcp.servers": {
    "voxburst": {
      "command": "npx",
      "args": ["@voxburst/mcp-server"],
      "env": {
        "VOXBURST_API_KEY": "vb_live_xxxxxxxxxxxxx"
      }
    }
  }
}

Available Tools

Post Management

create_post

Create a new post or schedule it for later.

list_posts

List recent posts from the workspace.

get_post

Get a single post by ID.

delete_post

Delete a post by ID. Only draft and scheduled posts can be deleted — published posts cannot be deleted through this tool.

update_post

Update a draft or scheduled post.

cancel_post

Cancel a scheduled or draft post by postId. Cannot cancel posts that are already published or being published.

retry_post

Retry a post by postId. Works on posts with status failed (all platforms failed) or partial (some platforms failed, others succeeded). Successfully-published platforms are never re-posted — only failed platforms are re-queued.

validate_content

Validate content against platform-specific rules before posting.

Example response:

{
  "valid": false,
  "platforms": {
    "TWITTER": {
      "valid": false,
      "errors": [
        { "code": "CONTENT_TOO_LONG", "message": "Content exceeds Twitter's 280 character limit (current: 312)" }
      ],
      "warnings": []
    },
    "INSTAGRAM": {
      "valid": true,
      "errors": [],
      "warnings": [
        { "code": "NO_MEDIA", "message": "Instagram feed posts require at least one image or video" }
      ]
    }
  }
}

The top-level valid is false if any platform has errors. warnings do not fail validation but indicate potential issues. Check per-platform errors to know exactly what to fix before posting.

Account Management

list_accounts

List all connected social media accounts. No parameters required.

get_account

Get details of a specific account by accountId.

Analytics

get_post_metrics

Get engagement metrics for a post (impressions, likes, shares, comments, clicks).

get_account_metrics

Get metrics for an account (followers, following, total posts, average engagement rate).

Available Resources

Resources provide read-only access to VoxBurst data via URI:

Example Usage

Once configured, you can ask your AI assistant to:

• “Post ‘Just shipped a new feature!’ to my Twitter and LinkedIn accounts.”
• “Schedule a post for next Monday at 10 AM: ‘Monday motivation…’”
• “How did my last post perform?”
• “Show me all my scheduled posts.”
• “Delete the draft post I created earlier.”

The MCP server handles translating these requests into VoxBurst API calls automatically.

Instagram

Instagram requires media on every post and a contentType to specify the post format. Always call list_accounts first to get the account ID — Instagram account IDs start with acc_.

Single image post

create_post(
  content: "Behind the scenes 📸",
  accountIds: ["acc_instagram_123"],
  contentType: "IMAGE",
  mediaUrls: ["https://cdn.example.com/photo.jpg"]
)

Carousel (2–10 images or videos)

create_post(
  content: "Swipe to see more →",
  accountIds: ["acc_instagram_123"],
  contentType: "CAROUSEL",
  mediaUrls: [
    "https://cdn.example.com/slide-1.jpg",
    "https://cdn.example.com/slide-2.jpg",
    "https://cdn.example.com/slide-3.jpg"
  ]
)

Reel (short-form video)

create_post(
  content: "Our latest drop 🔥",
  accountIds: ["acc_instagram_123"],
  contentType: "REEL",
  mediaUrls: ["https://cdn.example.com/reel.mp4"],
  firstComment: "#reels #newdrop #launch"
)

Scheduled post

create_post(
  content: "Launch day. Shipping now.",
  accountIds: ["acc_instagram_123"],
  contentType: "CAROUSEL",
  mediaUrls: [
    "https://cdn.example.com/launch-1.jpg",
    "https://cdn.example.com/launch-2.jpg"
  ],
  scheduledFor: "2026-06-01T15:00:00Z"
)

First comment with delay

create_post(
  content: "New product just dropped.",
  accountIds: ["acc_instagram_123"],
  contentType: "IMAGE",
  mediaUrls: ["https://cdn.example.com/product.jpg"],
  firstComment: "Shop the link in bio 👆",
  firstCommentDelay: 30
)

firstCommentDelay is in seconds. The example above posts the comment 30 seconds after the photo publishes.

Post Status Lifecycle

Understanding how post status flows helps you know which tool actions are valid at each point.

draft ──────────────→ scheduled ──→ publishing ──→ published
  ↑                       ↑               ↓              ↓
  │                       │           failed          partial
  │                       │               ↓              ↓
  └── update_post         └── (after    retry          retry
  └── cancel_post             unschedule)  ↓              ↓
  └── delete_post                       published      published

Which tools are available from each status:

retry_post re-queues only platforms with status: "failed". Platforms that already published are never re-posted — it is safe to call even on a partial post.

Security Notes

• API keys are passed via environment variables and never logged
• All API communication uses HTTPS
• The server has no persistent state between calls
• Runs in stdio mode — no network port is opened

Troubleshooting

Tool Response Shapes

What each tool returns so your agent knows what to expect.

list_accounts

[
  {
    "id": "acc_instagram_abc123",
    "platform": "instagram",
    "username": "mybrand",
    "displayName": "My Brand",
    "connected": true,
    "lastSync": "2026-05-30T10:00:00Z"
  },
  {
    "id": "acc_twitter_xyz456",
    "platform": "twitter",
    "username": "mybrand_x",
    "displayName": "My Brand X",
    "connected": true
  }
]

create_post — success

{
  "id": "post_abc123",
  "content": "Launch day. Shipping now.",
  "status": "scheduled",
  "scheduledFor": "2026-06-01T15:00:00Z",
  "contentType": "CAROUSEL",
  "platforms": [
    {
      "platform": "instagram",
      "accountId": "acc_instagram_abc123",
      "status": "pending",
      "platformPostId": null,
      "platformPostUrl": null,
      "publishedAt": null,
      "error": null
    }
  ],
  "createdAt": "2026-05-30T10:05:00Z"
}

get_post — after publishing

{
  "id": "post_abc123",
  "content": "Launch day. Shipping now.",
  "status": "published",
  "publishedAt": "2026-06-01T15:00:05Z",
  "platforms": [
    {
      "platform": "instagram",
      "status": "published",
      "platformPostUrl": "https://www.instagram.com/p/ABC123/",
      "publishedAt": "2026-06-01T15:00:05Z",
      "error": null
    }
  ]
}

get_post — partial failure

{
  "id": "post_abc123",
  "status": "partial",
  "platforms": [
    {
      "platform": "instagram",
      "status": "published",
      "platformPostUrl": "https://www.instagram.com/p/ABC123/",
      "error": null
    },
    {
      "platform": "twitter",
      "status": "failed",
      "platformPostUrl": null,
      "error": "Content exceeds Twitter's 280 character limit",
      "retryCount": 1
    }
  ]
}

list_posts

{
  "data": [
    {
      "id": "post_abc123",
      "content": "Launch day.",
      "status": "published",
      "publishedAt": "2026-06-01T15:00:05Z"
    },
    {
      "id": "post_def456",
      "content": "Coming soon...",
      "status": "scheduled",
      "scheduledFor": "2026-06-03T10:00:00Z"
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6InBvc3RfZGVmNDU2In0",
    "limit": 20
  }
}

validate_content — with errors

{
  "valid": false,
  "platforms": {
    "TWITTER": {
      "valid": false,
      "errors": [
        { "code": "CONTENT_TOO_LONG", "message": "Content exceeds Twitter's 280 character limit (current: 312)" }
      ],
      "warnings": []
    },
    "INSTAGRAM": {
      "valid": true,
      "errors": [],
      "warnings": [
        { "code": "NO_MEDIA", "message": "Instagram feed posts require at least one image or video" }
      ]
    }
  }
}

valid: false at the top level means at least one platform has errors. Warnings are advisory — they do not block posting.

retry_post

{
  "id": "post_abc123",
  "status": "publishing",
  "retriedPlatforms": [
    { "platform": "twitter", "retryCount": 2, "nextRetryAt": "2026-06-01T15:04:00Z" }
  ],
  "skippedPlatforms": []
}

If a platform has exhausted all 3 retries, it appears in skippedPlatforms with reason: "max_retries_exceeded". Use the REST API /v1/posts/:id/platforms/:platformId/fix to reset and resubmit.

Field Mapping Across Surfaces

Use this table when switching between MCP, REST API, TypeScript SDK, and Go SDK to avoid confusion.

Key differences to remember:

• MCP mediaUrls accepts public HTTPS URLs and registers them automatically. The REST API has no mediaUrls field — you must register or upload first, then pass the resulting mediaId as media.
• accountIds is always an array, even when posting to a single account: ["acc_abc123"].
• Platform constants are uppercase: "INSTAGRAM", "TWITTER". The account.platform field in responses is lowercase: "instagram", "twitter".

Common Failures Cookbook

Post fails immediately (validation error)

Your agent receives a 400 error before the post is created. Check validate_content first:

validate_content(
  content: "your caption",
  platforms: ["INSTAGRAM"]
)

Common causes: caption too long, wrong contentType, missing media for Instagram.

Post is created but status stays pending for a long time

Normal — posts go through a scheduling queue. Use get_post to poll. If status is still pending after 5 minutes, check the VoxBurst dashboard for queue status.

Post status is failed

get_post(postId: "post_abc123")

Read platforms[].error for the specific failure reason per platform. Common Instagram failures:

Then retry:

retry_post(postId: "post_abc123")

Post status is partial

Some platforms published, others failed. retry_post re-queues only the failed platforms — it will not re-post to platforms that already succeeded.

Platform has retryCount: 3 and is skipped by retry

The platform has exhausted automatic retries. Use the REST API directly:

curl -X POST https://api.voxburst.io/v1/posts/post_abc123/platforms/pp_xyz789/fix \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -d '{ "mediaUrl": "https://cdn.example.com/corrected-image.jpg" }'

Replace pp_xyz789 with the postPlatformId from get_post’s platforms array.

Consistency Reference

The MCP server, REST API, TypeScript SDK, and Go SDK all interact with the same VoxBurst backend. Each surface uses the same field semantics — only the naming conventions differ slightly.

If you are using the MCP server: Follow MCP field names only (accountIds, mediaUrls, mediaIds, contentType). The server handles the REST API translation.

If you are using the REST API directly: Use accountIds, media (for IDs), contentType. Register external URLs via POST /v1/media/register first.

If you are using the TypeScript SDK: Same field names as REST (accountIds, media, contentType). Use client.posts.create(), client.media.requestUploadURL().

If you are using the Go SDK: Same concepts, Go-idiomatic capitalization (AccountIds, Media, ContentType). Use client.Posts.Create(), client.Media.RequestUploadURL().

A post created via MCP, checked via REST, and monitored via the TypeScript SDK will have the same post.id and the same status values throughout.