io.github.ndesv21/socialclaw

Official17 tools

by ndesv21 · JavaScript

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

Schedule, publish, and track social media posts across 11+ platforms.

Topics

ai-agentscliopenclawsocial-publishingsocialclawai-agentautomationclaudecursormcpmcp-serverschedulersocial-mediamodel-context-protocolschedulingsocial-media-scheduleragentic-aichatgptclaude-codecodex

Captured live from the server via tools/list.

list_accounts

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

Parameters (1)

providerstring
Optional provider filter.

account_capabilities

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 (2)

accountIdstring
Optional account id.
providerstring
Optional provider filter.

connect_account

Start connecting a new social account. For OAuth providers this returns an authorizeUrl the user must open in a browser. Telegram requires botToken and chatId; Discord requires webhookUrl.

Parameters (4)

providerstringrequired
Provider to connect.
botTokenstring
Telegram bot token (telegram only).
chatIdstring
Telegram chat target, e.g. @yourchannel (telegram only).
webhookUrlstring
Discord channel webhook URL (discord only).

upload_asset

Upload media (image or video) to SocialClaw hosted storage. Provide either sourceUrl (a public URL the server downloads) or contentBase64. Returns an asset id and a public URL usable as media_link in schedules.

Parameters (3)

filenamestringrequired
Filename including extension, e.g. launch.png.
sourceUrlstring
Public URL to download the media from.
contentBase64string
Base64-encoded file content (alternative to sourceUrl).

validate_schedule

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 (1)

scheduleobjectrequired
SocialClaw schedule document. Minimal shape: { timezone, posts: [{ account, name, description, publish_at, media_link? }] }. Campaign documents use { timezone, campaigns: [...] }.

preview_campaign

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

Parameters (1)

scheduleobjectrequired
SocialClaw schedule document. Minimal shape: { timezone, posts: [{ account, name, description, publish_at, media_link? }] }. Campaign documents use { timezone, campaigns: [...] }.

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 (2)

scheduleobjectrequired
SocialClaw schedule document. Minimal shape: { timezone, posts: [{ account, name, description, publish_at, media_link? }] }. Campaign documents use { timezone, campaigns: [...] }.
idempotencyKeystring
Stable key to deduplicate retries.

publish_draft

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

Parameters (2)

runIdstringrequired
Draft run id.
startAtstring
Optional ISO-8601 publish start time.

list_posts

List posts in the workspace with optional filters.

Parameters (6)

runIdstring
statusstring
e.g. scheduled, published, failed, canceled.
accountstring
Account handle filter.
providerstring
campaignIdstring
limitnumber

get_post

Get one post including its delivery state and provider identifiers.

Parameters (1)

postIdstringrequired

post_attempts

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

Parameters (1)

postIdstringrequired

retry_post

Retry a failed post.

Parameters (1)

postIdstringrequired

cancel_post

Cancel a scheduled post before it publishes.

Parameters (1)

postIdstringrequired

run_status

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

Parameters (1)

runIdstringrequired

get_analytics

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

Parameters (3)

scopestringrequired
idstringrequired
windowstring
Optional analytics window, e.g. 7d.

workspace_usage

Get workspace usage counters and plan entitlement consumption.

No parameters.

workspace_health

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

Parameters (1)

providerstring
Optional provider to check connection health for.

README.md10 KBView on GitHub

<img src="https://raw.githubusercontent.com/ndesv21/socialclaw/main/.github/readme/logo.png" alt="SocialClaw logo" width="112"> <h1 align="center">SocialClaw</h1> Social media scheduling CLI and OpenClaw skill for AI agents posting to X, LinkedIn, Instagram, Facebook Pages, TikTok, Discord, Telegram, YouTube, Reddit, WordPress, and Pinterest. <a href="https://getsocialclaw.com">Website</a> · <a href="https://getsocialclaw.com/dashboard">Dashboard</a> · <a href="https://www.npmjs.com/package/socialclaw">npm</a> · <a href="https://github.com/ndesv21/socialclaw/tree/main/skill">Skill Bundle</a> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ndesv21/socialclaw/main/.github/readme/workflow-dark.png"> <img src="https://raw.githubusercontent.com/ndesv21/socialclaw/main/.github/readme/workflow-light.png" alt="SocialClaw turns prompts, workflows, and AI agents into scheduled publishing, retries, inspection, and analytics across social channels." width="100%"> </picture>

SocialClaw is the public home for:

the socialclaw npm CLI
the OpenClaw and ClawHub skill bundle
the Claude Code plugin and /socialclaw command asset
public usage docs, provider notes, and schedule examples

The hosted SocialClaw service lives at:

https://getsocialclaw.com

Install

bash

npm install -g socialclaw
socialclaw login
socialclaw accounts list --json

Install as an AI agent skill (Claude Code, Cursor, Cline, Codex, and more):

bash

npx skills add ndesv21/socialclaw

What the CLI covers

workspace API key login and hosted dashboard bootstrap
browser OAuth connect plus manual Discord and Telegram connect
hosted asset upload and deletion
schedule validation, campaign preview, apply, inspect, clone, and draft publishing
post, run, attempt, analytics, job, usage, and health inspection
provider-side deletion for supported published posts
Claude Code command installation through socialclaw install --claude

CLI at a glance

bash

socialclaw login
socialclaw accounts list --json
socialclaw assets upload --file ./image.png --json
socialclaw validate -f schedule.json --json
socialclaw apply -f schedule.json --json
socialclaw posts delete --post-id <post-id> --json

<details> <summary>Current help surface</summary>

text

____             _       _      ____ _
/ ___|  ___   ___(_) __ _| |    / ___| | __ ___      __
\___ \ / _ \ / __| |/ _` | |   | |   | |/ _` \ \ /\ / /
 ___) | (_) | (__| | (_| | |   | |___| | (_| |\ V  V /
|____/ \___/ \___|_|\__,_|_|    \____|_|\__,_| \_/\_/

socialclaw login
socialclaw accounts list --json
socialclaw assets upload --file <path> --json
socialclaw campaigns preview -f <schedule.(yaml|yml|json)> --json
socialclaw validate -f <schedule.(yaml|yml|json)> --json
socialclaw apply -f <schedule.(yaml|yml|json)> --json
socialclaw posts get --post-id <id> --json
socialclaw posts delete --post-id <id> --json
socialclaw status --run-id <id> --json
socialclaw analytics post --post-id <id> --json

</details>

Watch the Demo

<a href="https://www.youtube.com/watch?v=Biy8saQqf44"> <img src="https://raw.githubusercontent.com/ndesv21/socialclaw/main/.github/readme/socialclaw-demo-poster.png" alt="Watch the SocialClaw demo video" width="820"> </a> Click the image to open the demo video.

Built for Agent-Driven Publishing

Authentication and access

Running socialclaw login without an API key opens the hosted dashboard so the user can:

sign in with Google
connect social accounts
create or copy a workspace API key
activate a trial or paid plan for CLI and API access

Important:

the CLI works against a deployed SocialClaw workspace via API key auth
an API key alone is not enough for agent execution; the workspace must also have an active trial or paid plan
if a command returns plan_required or subscription_*, go to https://getsocialclaw.com/pricing or https://getsocialclaw.com/dashboard

Quick start

bash

socialclaw login
socialclaw login --api-key <workspace-key> --base-url https://getsocialclaw.com
socialclaw accounts list --json
socialclaw accounts capabilities --provider pinterest --json
socialclaw accounts connect --provider pinterest --open
socialclaw accounts connect --provider discord --webhook-url <webhook-url> --json
socialclaw accounts connect --provider telegram --bot-token <bot-token> --chat-id @yourchannel --json
socialclaw assets upload --file ./image.png --json
socialclaw campaigns preview -f schedule.json --json
socialclaw validate -f schedule.json --json
socialclaw apply -f schedule.json --json
socialclaw posts delete --post-id <post-id> --json
socialclaw workspace health --json
socialclaw usage --json

Agent integrations

MCP server

The package ships a Model Context Protocol server. Any MCP client (Claude Code, Claude Desktop, Cursor, and others) gets 17 validation-first publishing tools over your connected workspace accounts: list accounts and capabilities, upload media, validate and preview schedules, apply with idempotency keys, publish drafts, and inspect posts, attempts, runs, analytics, usage, and health.

Claude Code:

bash

claude mcp add socialclaw \
  --env SOCIALCLAW_API_KEY=sc_live_your_key \
  -- npx -y socialclaw mcp

Claude Desktop, Cursor, and other JSON-configured clients:

json

{
  "mcpServers": {
    "socialclaw": {
      "command": "npx",
      "args": ["-y", "socialclaw", "mcp"],
      "env": {
        "SOCIALCLAW_API_KEY": "sc_live_your_key"
      }
    }
  }
}

If you have already run socialclaw login --api-key <key>, the server reuses the saved credentials and the env block is unnecessary. See getsocialclaw.com/mcp for the full tool list.

Claude Code plugin

Install the packaged Claude Code plugin from inside Claude Code:

shell

/plugin marketplace add ndesv21/socialclaw
/plugin install socialclaw@socialclaw

This installs the marketplace plugin from skills/socialclaw/ with metadata from .claude-plugin/. It is the cleanest option if you want Claude to auto-invoke SocialClaw when a user asks to connect accounts, upload media, schedule posts, inspect delivery, or check analytics.

Claude slash command and skill file

If you want the explicit /socialclaw command instead of the full plugin flow:

bash

socialclaw install --claude

That installs the bundled command file from skill/claude/socialclaw.md into ~/.claude/commands/socialclaw.md.

Use this path when you want a lightweight Claude Code setup that:

exposes one clear SocialClaw command
keeps the workspace API key flow explicit
still lets Claude use the same hosted SocialClaw API and CLI workflow

OpenClaw and ClawHub

The OpenClaw-compatible skill bundle lives in skill/.

It is designed for OpenClaw and other compatible agent runtimes that can load a SKILL.md, work from a workspace API key, and call either:

the SocialClaw HTTP API directly
the socialclaw CLI as a client for the hosted service

This is the bundle to publish to ClawHub for OpenClaw discovery.

Other agents

SocialClaw is not limited to one agent framework. The repo also includes an agent manifest in skill/agents/openai.yaml, and the CLI works well for any runtime that can execute shell commands or make HTTP requests.

That makes SocialClaw a good fit for:

Codex and terminal-native agent workflows
Claude Code via plugin or command file
OpenClaw and ClawHub skills
custom internal agents that need one stable publishing surface for social channels

In practice, all of these share the same model:

connect customer accounts inside SocialClaw
create a workspace API key
upload media, validate, apply, inspect, analyze, and optionally delete supported posts through the hosted service

Supported providers

X
Facebook Pages
Instagram Business
Instagram standalone professional accounts
LinkedIn profile
LinkedIn page
Pinterest
TikTok
Discord
Telegram
YouTube
Reddit
WordPress

Pinterest is exposed as the pinterest provider in the public CLI and skill bundle. Its main publish target is board-centric, with support for standard pins, video pins, multi-image pins, board creation and section or catalog discovery, plus pin and account analytics. Product, collection, and idea surfaces should be treated as capability-gated or beta rather than assumed for every workspace.

TikTok supports one video or one photo gallery per post. Photo galleries can include up to 35 images and expose autoAddMusic plus photoCoverIndex; selecting a specific TikTok song or sound is not available through TikTok's Content Posting API. For photo galleries, normalize images before upload, preferably to 1080x1920 JPEGs for vertical slides or another standard TikTok-compatible aspect/size. Oversized or unusual image dimensions may pass SocialClaw validation and initial TikTok acceptance, then fail later with picture_size_check_failed; reconcile photo posts after publish to confirm TikTok reports PUBLISH_COMPLETE.

Publishing

Bump the version with npm version:

bash

npm version patch
git push && git push --tags
npm publish --access public

To sync reference files manually after editing skill/references/:

bash

npm run sync:references

Notes

Users connect accounts inside the hosted SocialClaw dashboard.
The dashboard and API live at https://getsocialclaw.com.
The npm package ships the CLI, skill docs, Claude Code plugin, and command asset.

Install

Configuration

Environment variables

SOCIALCLAW_API_KEYrequiredsecret

SocialClaw workspace API key from https://getsocialclaw.com/dashboard

claude_desktop_config.json

{
  "mcpServers": {
    "socialclaw": {
      "command": "npx",
      "args": [
        "-y",
        "socialclaw@0.1.16"
      ],
      "env": {
        "SOCIALCLAW_API_KEY": "<YOUR_SOCIALCLAW_API_KEY>"
      }
    }
  }
}