io.github.ndesv21/socialclaw

Measured conclusion: Deep-tested. L2 outcome: tools_ok.

Connect any AI agent to 11+ social platforms: schedule, publish & track posts via hosted MCP.

Add to your agent

Copy this into your MCP client config:

{
  "mcpServers": {
    "socialclaw": {
      "url": "https://getsocialclaw.com/mcp",
      "transport": "streamable-http"
    }
  }
}

Measured tools (34)

• list_accounts read-only

  List connected social accounts in the SocialClaw workspace. Optionally filter by provider (x, facebook, instagram_business, instagram, threads, linkedin, linkedin_page, pinterest, tiktok, telegram, discord, youtube, reddit, wordpress).

  Parameters:

  • provider — string — Optional provider filter.

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• account_capabilities read-only

  Get publish capabilities and provider rules for connected accounts: what media is allowed, text limits, and whether publishing is currently possible. Pass accountId for one account, or provider to filter, or neither for all.

  Parameters:

  • provider — string — Optional provider filter.
  • accountId — string — Optional account id.

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• connect_account

  Start connecting one of the user's own social accounts to their SocialClaw workspace. For most providers this returns an authorizeUrl; give it to the user so they sign in with the provider themselves (SocialClaw never sees their password). Telegram and Discord have no sign-in page: Telegram takes the bot token and chat id of a bot the user created and made admin of their channel, and Discord takes a webhook URL the user created for their channel. Only pass values the user gave you for this purpose.

  Parameters:

  • provider (required) — string — Provider to connect.
  • chatId — string — Telegram chat target, e.g. @yourchannel (telegram only).
  • botToken — string — Telegram only: token of the user's own bot, from @BotFather.
  • webhookUrl — string — Discord only: webhook URL the user created in their channel settings.

  Hints: read-only no · destructive no · idempotent no · open-world yes

• upload_asset

  Add an image or video to the user's SocialClaw media library so it can be attached to a post. Pass exactly one of: file (a file the user attached in this chat), sourceUrl (a direct public http(s) link to the image or video file, not a web page), or contentBase64 (small files only). Files up to 1 GB are supported through file or sourceUrl. The result is the asset: when status is ready, use its publicUrl as media_link in validate_schedule/apply_schedule. Large videos may come back with status uploading; then call get_asset with the asset id until status is ready (or failed) before scheduling.

  Parameters:

  • file — object — A file the user attached in the conversation.
  • filename — string — Optional filename including extension, e.g. launch.png. Inferred from the file or URL when omitted.
  • sourceUrl — string — Direct public http(s) URL of the image or video file.
  • contentBase64 — string — Base64-encoded file content. Small files only; prefer file or sourceUrl.

  Hints: read-only no · destructive no · idempotent no · open-world yes

• get_asset read-only

  Get one media asset from the user's SocialClaw library by id, including its status (uploading, ready, or failed), import progress, and publicUrl. Use it after upload_asset returns status uploading, until the asset is ready.

  Parameters:

  • assetId (required) — string — Asset id returned by upload_asset or list_assets.

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• validate_schedule read-only

  Validate a schedule document against provider rules, media limits, account state, and publish times WITHOUT creating any posts. Always run this before apply_schedule.

  Parameters:

  • schedule (required) — object — SocialClaw schedule document. Minimal shape: { timezone, posts: [{ account, name, description, publish_at, media_link? }] }. Campaign documents use { timezone, campaigns: [...] }. Per-post provider settings go in settings, e.g. TikTok inbox mode: settings: { tiktokPostMode: "draft" } sends the media to TikTok's inbox notification flow instead of publishing, and the creator finishes the post inside the TikTok app.

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• preview_campaign read-only

  Preview how a campaign schedule document expands into concrete posts and steps without creating anything.

  Parameters:

  • schedule (required) — object — SocialClaw schedule document. Minimal shape: { timezone, posts: [{ account, name, description, publish_at, media_link? }] }. Campaign documents use { timezone, campaigns: [...] }. Per-post provider settings go in settings, e.g. TikTok inbox mode: settings: { tiktokPostMode: "draft" } sends the media to TikTok's inbox notification flow instead of publishing, and the creator finishes the post inside the TikTok app.

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• apply_schedule

  Create a publishing run from a schedule document. Posts are scheduled or published through connected accounts. Send an idempotencyKey so retries do not create duplicate runs.

  Parameters:

  • schedule (required) — object — SocialClaw schedule document. Minimal shape: { timezone, posts: [{ account, name, description, publish_at, media_link? }] }. Campaign documents use { timezone, campaigns: [...] }. Per-post provider settings go in settings, e.g. TikTok inbox mode: settings: { tiktokPostMode: "draft" } sends the media to TikTok's inbox notification flow instead of publishing, and the creator finishes the post inside the TikTok app.
  • idempotencyKey — string — Stable key to deduplicate retries.

  Hints: read-only no · destructive no · idempotent no · open-world yes

• publish_draft

  Publish a previously created draft run, optionally at a given ISO-8601 start time.

  Parameters:

  • runId (required) — string — Draft run id.
  • startAt — string — Optional ISO-8601 publish start time.

  Hints: read-only no · destructive no · idempotent no · open-world yes

• list_posts read-only

  List posts in the workspace with optional filters.

  Parameters:

  • limit — number — Maximum posts to return. Defaults to 20 and is capped at 50.
  • runId — string
  • offset — number — Offset for paging through results.
  • status — string — e.g. scheduled, published, action_required, failed, canceled.
  • account — string — Account handle filter.
  • provider — string
  • campaignId — string

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• list_assets read-only

  List media (images/videos) the user has uploaded to their SocialClaw library, newest first. Each asset includes a publicUrl usable directly as media_link in validate_schedule/apply_schedule. Use this to find a previously uploaded file (e.g. from the dashboard) to post. Optionally filter by kind (image/video), mime, or a text query over filename/id.

  Parameters:

  • kind — string — Filter by media kind: image or video.
  • mime — string — Optional mime prefix filter, e.g. video/mp4.
  • sort — string — created_desc (default, newest first) or created_asc.
  • limit — number — Maximum assets to return. Defaults to 24, capped at 48.
  • query — string — Optional text match over filename, id, kind, mime, or url.

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• get_post read-only

  Get one post including its delivery state and provider identifiers.

  Parameters:

  • postId (required) — string

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• post_attempts read-only

  List publish attempts for a post, including provider errors. Use this to debug failed posts.

  Parameters:

  • postId (required) — string

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• retry_post

  Retry a failed post.

  Parameters:

  • postId (required) — string

  Hints: read-only no · destructive no · idempotent no · open-world yes

• cancel_post destructive

  Cancel a scheduled post before it publishes.

  Parameters:

  • postId (required) — string

  Hints: read-only no · destructive yes · idempotent yes · open-world no

• run_status read-only

  Get the status summary of a publishing run and its posts.

  Parameters:

  • runId (required) — string

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• get_analytics read-only

  Get analytics snapshots for a post, an account, or a run. scope must be post, account, or run; id is the matching identifier.

  Parameters:

  • scope (required) — string
  • id (required) — string
  • window — string — Optional analytics window, e.g. 7d.

  Hints: read-only yes · destructive no · idempotent yes · open-world yes

• refresh_analytics

  Fetch fresh analytics for a published post from the provider and store a new snapshot, then return it. Supported providers: Instagram, TikTok, YouTube, Reddit, X, Pinterest, Snapchat (others return an unsupported snapshot). Call this before get_analytics when you need current numbers rather than the last stored snapshot.

  Parameters:

  • postId (required) — string — The published post id to refresh.
  • window — string — Optional analytics window, e.g. 7d (default lifetime).

  Hints: read-only no · destructive no · idempotent yes · open-world yes

• list_instagram_media read-only

  List an Instagram account's recent posts (caption, permalink, timestamp, comment count) so you can find one to read or moderate comments on. account is the connected-account id or handle.

  Parameters:

  • account (required) — string — Instagram connected-account id or handle.
  • after — string — Pagination cursor from a previous response.
  • limit — number — Max media to return (default 25, capped at 100).

  Hints: read-only yes · destructive no · idempotent yes · open-world yes

• get_instagram_comments read-only

  Read the comments and replies people left on one of the user's own Instagram posts, so the user can review and answer them. Use list_instagram_media first to get a mediaId.

  Parameters:

  • account (required) — string — Instagram connected-account id or handle.
  • mediaId (required) — string — The IG media id from list_instagram_media.
  • after — string — Pagination cursor from a previous response.
  • limit — number — Max comments to return (default 25, capped at 100).

  Hints: read-only yes · destructive no · idempotent yes · open-world yes

• reply_instagram_comment

  Reply to an Instagram comment on the user's media.

  Parameters:

  • account (required) — string — Instagram connected-account id or handle.
  • commentId (required) — string
  • message (required) — string — The reply text.

  Hints: read-only no · destructive no · idempotent no · open-world yes

• hide_instagram_comment

  Hide or unhide an Instagram comment on the user's media. Set hidden=false to unhide.

  Parameters:

  • account (required) — string — Instagram connected-account id or handle.
  • commentId (required) — string
  • hidden — boolean — true to hide (default), false to unhide.

  Hints: read-only no · destructive no · idempotent yes · open-world yes

• delete_instagram_comment destructive

  Permanently delete an Instagram comment on the user's media. Prefer hide_instagram_comment when unsure.

  Parameters:

  • account (required) — string — Instagram connected-account id or handle.
  • commentId (required) — string

  Hints: read-only no · destructive yes · idempotent no · open-world yes

• get_instagram_media_insights read-only

  Get analytics for one Instagram post (reach, likes, comments, saved, shares, views). Use list_instagram_media for the mediaId.

  Parameters:

  • account (required) — string — Instagram connected-account id or handle.
  • mediaId (required) — string
  • mediaProductType — string — Optional: FEED, REELS, or STORY — refines which metrics are requested.

  Hints: read-only yes · destructive no · idempotent yes · open-world yes

• get_instagram_profile read-only

  Get an Instagram account's profile stats: followers, follows, media count, bio.

  Parameters:

  • account (required) — string — Instagram connected-account id or handle.

  Hints: read-only yes · destructive no · idempotent yes · open-world yes

• get_instagram_account_insights read-only

  Get an Instagram account's insight trend (a daily time series, e.g. reach) over the last N days.

  Parameters:

  • account (required) — string — Instagram connected-account id or handle.
  • days — number — Window in days (2-30, default 14).
  • metric — string — Account metric, default reach (e.g. reach, profile_views, accounts_engaged).

  Hints: read-only yes · destructive no · idempotent yes · open-world yes

• react_instagram_message

  React to a received Instagram direct message (e.g. love).

  Parameters:

  • account (required) — string — Instagram connected-account id or handle.
  • conversationId (required) — string
  • messageId (required) — string
  • recipientId (required) — string — The other participant's Instagram-scoped user id (IGSID).
  • reaction — string — Reaction name, default love.

  Hints: read-only no · destructive no · idempotent no · open-world yes

• list_instagram_mentions read-only

  List recent @mentions of the workspace's Instagram accounts (captured from Instagram mention webhooks).

  Parameters:

  • limit — number — Max mentions (default 30, capped at 100).

  Hints: read-only yes · destructive no · idempotent yes · open-world yes

• list_instagram_conversations read-only

  List the Instagram direct-message conversations for an account, most recent first. Each conversation includes `counterpart` (the other person's {id, username}) — use its id as the recipientId when replying; `participants` also lists the account itself.

  Parameters:

  • account (required) — string — Instagram connected-account id or handle.
  • after — string — Pagination cursor from a previous response.
  • limit — number — Max conversations (default 25, capped at 100).

  Hints: read-only yes · destructive no · idempotent yes · open-world yes

• get_instagram_messages read-only

  Read the messages in an Instagram direct-message conversation.

  Parameters:

  • account (required) — string — Instagram connected-account id or handle.
  • conversationId (required) — string — Conversation id from list_instagram_conversations.
  • after — string — Pagination cursor from a previous response.
  • limit — number — Max messages (default 25, capped at 100).

  Hints: read-only yes · destructive no · idempotent yes · open-world yes

• send_instagram_message

  Send an Instagram direct message — a text reply, or an image/video attachment via attachment_url. Only allowed within 24 hours of the recipient's last message unless a message tag (e.g. HUMAN_AGENT) is supplied.

  Parameters:

  • account (required) — string — Instagram connected-account id or handle.
  • conversationId (required) — string — Conversation id (for routing/storage).
  • recipientId (required) — string — The recipient's Instagram-scoped user id (IGSID).
  • tag — string — Optional message tag, e.g. HUMAN_AGENT, to reply outside the 24h window.
  • text — string — Message body (omit when sending an attachment).
  • attachment_url — string — Public URL of an image/video to send as an attachment.
  • attachment_type — string — Attachment type: image (default), video, or audio.

  Hints: read-only no · destructive no · idempotent no · open-world yes

• workspace_usage read-only

  Get workspace usage counters and plan entitlement consumption.

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• workspace_health read-only

  Get workspace health, including connection state across providers. Pass provider to check one provider's connections.

  Parameters:

  • provider — string — Optional provider to check connection health for.

  Hints: read-only yes · destructive no · idempotent yes · open-world no

• get_profile read-only

  Identify the connected SocialClaw workspace: its stable id, name, and plan. Use it to confirm which workspace you are acting on.

  Hints: read-only yes · destructive no · idempotent yes · open-world no

Publisher website Repository

Measured by MCPYP probing. Untested fields are omitted, never estimated. Listing is always free; MCPYP never proxies calls or stores user tokens.