Sooshie MCP Server

An MCP (Model Context Protocol) server that lets AI assistants like Claude manage your social media through Sooshie — schedule posts, generate AI captions, manage accounts, and more.

What is this?

Connect your AI assistant to your Sooshie workspace and manage social media through natural conversation:

• "Schedule a post about our new product launch for tomorrow at 9am on Instagram and Facebook"
• "What posts do I have scheduled for this week?"
• "Generate a witty caption about our summer sale for TikTok"
• "How many failed posts do I have?"

Tools (63)

Every tool works with an API key. Admin-only actions — managing members, billing, approving posts, bulk changes, disconnecting accounts, revoking keys and team comments — need a signed-in admin in the Sooshie app, so they aren't exposed here.

Posts

| Tool | Description | |------|-------------| | list_posts | List posts with optional status/date/queued filters | | get_post | Get a specific post by ID | | create_post | Create a new post (draft, draft with a planned date, scheduled, or publish now); a repeated idempotency_key returns the original post unchanged; auto_crop: true crops its images per target | | update_post | Update a draft, scheduled, failed or partly failed post: content, media, targets or schedule (status: "draft" unschedules and keeps the date; scheduled_for: null unschedules and clears it); auto_crop: true crops its images per target | | schedule_post | Schedule a post (including a planned draft) for a specific date/time | | publish_post | Publish a post immediately | | get_post_comments | Get the team comments on a post | | submit_post_for_review | Submit a post for approval | | get_post_logs | Get the activity log for a post | | get_failed_post_count | Get the count of failed posts |

Planned dates vs. scheduling. scheduled_for on its own schedules the post: it auto-publishes at that time. To give a draft a date without scheduling it (as in the dashboard), send scheduled_for together with status: "draft" to create_post or update_post; the post stays a draft and is never published automatically. On a scheduled post, update_post with status: "draft" unschedules it and keeps the date. Use schedule_post to schedule a planned draft for real.

Per-account text and limits. content is shared by every target. To give one account its own text, set platform_overrides[accountId].content, for example platform_overrides: { "<threads account id>": { content: "Short version for Threads" } } (list_accounts gives each account's id and platform; get_post shows a post's targets and stored overrides). On update_post, platform_overrides replaces every account's overrides, so send them all. Each account's text must fit its platform: Threads 500, Instagram 2200, TikTok 2200 (a TikTok photo post's description 4000), YouTube 5000, Facebook 63,206 characters (Stories send no text). Scheduling or publishing (create_post with scheduled_for or publish_now, update_post/schedule_post that leave a post scheduled, publish_post, add_post_to_queue) is refused with 422 VALIDATION_ERROR when any target not yet sent is over its limit:

{ "error": { "code": "VALIDATION_ERROR",
  "message": "Text is too long for Threads account <id> (510/500). ... Resend it together with the rest of your original request (media, auto_crop, other fields), or those changes are lost.",
  "details": [{ "account_id": "<id>", "platform": "threads", "limit": 500, "length": 510,
    "fix": { "tool": "update_post", "action": "shorten_text", "post_id": "<post>", "account_id": "<id>",
      "field": "platform_overrides.<id>.content", "max_length": 500, "length": 510,
      "keep_platform_overrides": { "<instagram id>": { "mediaUrls": ["…crop…"] } },
      "note": "Write this account's text yourself, at most 500 characters, …" } }] } }

The MCP server includes the error's details in the tool error (Sooshie API error (VALIDATION_ERROR): … Details: [...]). A shorten_text fix is an edit, not a call to send as is: write your own text of at most max_length characters at field, send keep_platform_overrides with it (update_post replaces all overrides), and resend the rest of your original request too. Changing a TikTok account's text needs the owner's consent again (tiktok_consent: true). Text that is still a <rewrite in at most N characters> placeholder is refused with 422.

A draft is saved anyway, and the response lists issues: [{ account_id, platform, code, limit?, length?, message }] with everything that would block scheduling it (content_too_long, media_format, tiktok_settings).

Recommendations. create_post and update_post responses also carry recommendations: [{ account_id, platform, code, message, fix }] when there is something to fix (not with publish_now): content_too_long (with limit and length; on a draft it is also in issues, here with its shorten_text fix), image_aspect_mismatch (a photo outside the shape the platform accepts, e.g. 9:16 on an Instagram post; fix is { tool: "update_post", args: { post_id, auto_crop: true } }, or a crop_image call when the account sets its own media), suggest_auto_crop (a photo off the format's preferred shape, e.g. a landscape Story; plain feed posts aren't nagged about landscape photos) and auto_crop_rate_limited (retry that image with crop_image later). Check issues and recommendations and apply each fix before scheduling. Both are left out when empty. Image shapes come from the media library or the image's header; images of unknown size are skipped.

TikTok consent. TikTok only accepts content its account owner has explicitly agreed to post. create_post, update_post, schedule_post, publish_post and add_post_to_queue take tiktok_consent: true; set it only after the user has reviewed the post and agreed to TikTok's Music Usage Confirmation (and Branded Content Policy for branded content). Without it, scheduling, queueing or publishing to TikTok fails with TIKTOK_CONSENT_REQUIRED, and it is needed again whenever the caption, media or TikTok settings change.

Queue

| Tool | Description | |------|-------------| | get_queue_slots | Get the weekly posting slots, timezone, and upcoming slot times | | get_next_queue_slot | Get the next free posting slot | | add_post_to_queue | Schedule a post into the next free slot (or queue it on approval) |

Posting slots are edited in the Sooshie app. Changing them needs an admin user session, so the API rejects API keys and there is no MCP tool for it.

Accounts and workspace

| Tool | Description | |------|-------------| | list_accounts | List connected social accounts | | check_account_health | Check an account's connection and whether it is locked (beyond the plan's account limit) | | get_workspace | Get the API key's workspace | | get_workspace_members | List workspace team members |

AI (counts toward the workspace's monthly AI text allowance)

| Tool | Description | |------|-------------| | generate_content | Generate post content in one of 7 tones | | rewrite_content | Rewrite content (shorter, longer, more professional/casual/engaging, improve) | | generate_alt_text | Generate alt text for an image | | suggest_hashtags | Suggest hashtags for a topic | | generate_caption / generate_hooks / repurpose_content | Free, rate-limited writing tools |

Analytics and campaigns

| Tool | Description | |------|-------------| | get_analytics | Dashboard data for a date range (optionally one campaign) | | get_analytics_summary | AI summary of analytics data | | export_analytics | Export overview, posts or engagement data as CSV | | get_best_times | Best hours and weekdays to post, from your published posts | | get_content_decay | Median engagement and views at days 1–365 after publishing | | list_campaigns | List campaigns; include_stats adds each one's lifetime rollup | | get_campaign_stats | A campaign's totals, per-platform breakdown and top posts | | create_campaign / update_campaign / delete_campaign | Manage campaigns |

Hashtag groups

| Tool | Description | |------|-------------| | list_hashtag_groups | List hashtag groups | | create_hashtag_group / update_hashtag_group / delete_hashtag_group / duplicate_hashtag_group | Manage groups |

Inbox

| Tool | Description | |------|-------------| | list_inbox | Posts with comments, newest first | | get_inbox_comments | Comments on a published post | | reply_to_comment | Reply on the platform |

Media and automations

| Tool | Description | |------|-------------| | upload_media | Upload an image or video | | crop_image | Crop a workspace image to a platform's shape (4:5, 1:1, 1.91:1, 16:9, 9:16); framed on the image's main subjects (shown whole on a blurred background only when a crop would cut them off), or focus {x, y} | | delete_media | Delete uploaded media | | list_media_libraries | List Media Libraries (My Media plus custom libraries) with item counts and read_only | | get_media_library | A library and its Brief (purpose, background cards, image overview) to write posts with | | list_library_items | A library's files with url, ai_metadata and usage_count; limit (max 100), cursor, hide_used | | list_automation_rules / get_automation_rule | Media Library automation rules (Pro and above) | | create_automation_rule / update_automation_rule / delete_automation_rule | Manage rules |

To post a library file, pass its url in create_post's media_urls; ai_metadata describes the image or video. The library tools need an API key with the media_pools:read scope and work on every plan: without Pro, custom libraries are read-only (no uploads or AI), but their files can still be listed and posted. Library uploads, edits and AI generation aren't available through MCP.

crop_image saves the crop as a new file (counted toward storage) and returns its url, with framing: how it was framed. Without focus, Sooshie frames the image's main subjects (the people or product, from its Media Library analysis or a quick image check, at no cost to your AI allowance): "subject" when a crop to the shape keeps them (the largest crop around them; trimming only the margin or a sliver of the outermost subjects, at most 10%, still crops, as does a subject filling the photo), "fit" only when a crop would cut people or the product off (for example a group spread across a wide photo cropped to 4:5: the whole group is shown, scaled down onto a blurred, dimmed copy of the photo), or "attention" when no subject could be found (the most eye-catching area). focus gives "focus". To post it to one account, put that url in platform_overrides[accountId].mediaUrls, keeping the original in media_urls for the others. Recommended aspects: Instagram 4:5 (9:16 for Stories/Reels), Facebook 1.91:1 (9:16 for Stories/Reels), Threads 1:1, YouTube 16:9, TikTok 9:16. It takes static JPEG, PNG or WebP images from the workspace's own Sooshie media (upload other images with upload_media first), never upscales, and needs the media:write scope.

auto_crop. create_post and update_post take auto_crop: true to do this for every target: each still image in media_urls is cropped to the account's shape (the Story/Reel 9:16 when its platformData sets one, else Instagram 4:5, Facebook 1.91:1, Threads 1:1) and saved as that account's platform_overrides[accountId].mediaUrls, before the post is saved (and before publish_now sends it). One crop is made per image and shape and shared across accounts; an image already in an account's shape is posted as it is (no new file). It never replaces mediaUrls an account already has in its overrides, keeps videos as they are, leaves YouTube targets (YouTube posts are video) and TikTok targets alone (consent covers the exact media the owner reviewed: use crop_image and show them), and only crops the workspace's own media. It needs the media:write scope. Crops count toward storage and toward the crop rate limit crop_image uses (30 a minute), at most 20 per request. Crops are framed like crop_image's without focus. The post is saved either way; the response's auto_crop: { cropped, framing: { subject, fit, attention }, skipped: [{ account_id, url, code, reason }] } counts how the crops were framed and lists what kept its original, with a code for programs (for example storage_limit, rate_limited, unsupported, tiktok). Send auto_crop_accounts: [accountId, ...] (the post's targets only) to crop for just those accounts, for example ones you just added. On update_post it crops the new media_urls, else the stored ones, for the targets not yet sent. Changing media_urls drops crops auto_crop made earlier (Sooshie marks them), so those accounts use the new media, or get new crops when auto_crop is sent again; mediaUrls you set yourself are kept.

Links, reports, webhooks and keys

| Tool | Description | |------|-------------| | list_links / create_link | Tracked short links | | list_reports / create_report | Shareable analytics report links | | list_webhooks / get_webhook / create_webhook / update_webhook / delete_webhook | Webhook subscriptions | | list_api_keys | List API keys |

Supported Platforms

Facebook, Instagram, Threads, YouTube and TikTok.

Setup

1. Get your API key

1. Sign up at sooshie.app
2. Go to Settings > API Keys
3. Create a new API key (starts with sk_live_)

2. Install

npm install -g @sooshie/mcp-server

Or run directly with npx:

npx @sooshie/mcp-server

3. Configure Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "sooshie": {
      "command": "npx",
      "args": ["-y", "@sooshie/mcp-server"],
      "env": {
        "SOOSHIE_API_KEY": "sk_live_your_key_here",
        "SOOSHIE_URL": "https://sooshie.app"
      }
    }
  }
}

4. Restart Claude Desktop

The Sooshie tools will appear in Claude's tool list.

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | SOOSHIE_API_KEY | Yes | — | Your Sooshie API key (sk_live_...) | | SOOSHIE_URL | No | https://sooshie.app | Sooshie instance URL |

Examples

Create a post:

"Create a draft post about our upcoming webinar on social media strategy. Target Instagram and LinkedIn."

Schedule content:

"Schedule a post for next Tuesday at 10am EST: 'Excited to announce our new AI features! Try them free at sooshie.app'"

Generate captions:

"Generate 3 different captions for a photo of our team volunteer event. Make them professional for LinkedIn."

Check analytics:

"What posts did I publish this week? Which ones are scheduled for next week?"

Manage team:

"Invite [email protected] as an admin to our workspace"

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode
npm run dev

License

MIT

Links

• Sooshie — Social media scheduling platform
• Documentation — Full setup guide
• MCP Protocol — Model Context Protocol specification