title: SocialBlast AI emoji: 📬 colorFrom: pink colorTo: blue sdk: docker app_port: 7860 pinned: false short_description: Open-source social media approval queue demo

What's new in v0.6

The biggest jump since launch. Six new things to know.

  • Campaign Wizard at /wizard. One sentence + one face photo = a week of social posts. Premium hand-tuned templates work without any OpenAI key. Full-screen scroll-snap result feed shows every post before anything hits your queue.
  • HiggsField native integration via the official higgsfield-client Python SDK. Unlocks 17+ premium video models in one place: Seedance 2.0, Kling 2.6, Grok Video, Cinematic Studio 3.0, Marketing Studio Video, and more. Replicate stays as a clean fallback.
  • ElevenLabs voice cloning in the Brand Kit. Upload 1-3 minutes of your voice. Every AI video now narrates in your voice. Multilingual.
  • One-click post enrichment. Click Enhance on any pending post in the inbox. The pipeline runs caption → AI image → AI voice → AI video in the background. The post stays pending until you press Approve.
  • Virality predictor (via HiggsField) scores a caption per platform before you publish. Built-in MCP tool, so Claude can run it directly.
  • Health & status surfaces.
    • GET /api/status returns which backends are connected. No secrets.
    • python -m dashboard.health is the CLI version. Useful for first-run debug.
    • Settings page shows the same data with live green/red indicators.

Plus these 6 new MCP tools for campaign and virality work: socialblast_generate_campaign, socialblast_enrich_post, socialblast_enrich_campaign, socialblast_predict_virality, socialblast_status, socialblast_list_pending. Drive the full pipeline from Claude Desktop or Claude Code.

Every change still respects the approval queue. Nothing publishes without a human pressing Approve. That is not optional, that is the spine.

Try it without installing

Two ways to kick the tyres before you clone:

🖥️ Live dashboard demo

A public, read-only copy of the dashboard runs on Hugging Face Spaces with curated dummy posts across every platform, calendar, and published feed. Actions are disabled (the safety story stays honest) but you can click around the whole UI.

Open the demo →

🤖 The MCP server in Claude

Five-minute setup to plug the 15-tool MCP server into Claude Desktop or Claude Code. Every write goes through your local approval queue by default, and four extra direct-write tools are available behind an opt-in flag.

Five-minute MCP setup →

What it looks like

Why this exists

Most social media tools fall into two camps:

  • Schedulers (Buffer, Hootsuite, Later) — great at queuing, terrible at content. You still write everything yourself.
  • AI writers (Jasper, Copy.ai) — great at drafts, terrible at execution. They don't post anywhere.

SocialBlast AI is the missing middle. The AI knows your voice (because you trained it on your samples), the dashboard knows your platforms (because every account is connected), and a human approves every single thing before it leaves the door. No silent automation. No "trust the algorithm." Just a faster version of the workflow you'd run by hand.

Pitch in one sentence: It's the post pipeline a solo creator and a 100-page agency can run on the same software.

Features

Platform adapters — 5 live channels, 2 in code awaiting review

Facebook facebook_api.py — 20 methods

  • Text, image & video posts
  • Scheduled (future) posts
  • Edit & delete posts
  • Post permalinks
  • Page info & fan count
  • Comment replies
  • Hide / unhide comments
  • Bulk hide / delete / unhide
  • Negative sentiment filter
  • Top commenters extraction
  • Direct messages
  • Full insights suite

Instagram instagram_api.py — 6 methods

  • Image publishing (two-step container flow via Graph API)
  • Reels publishing (video upload + publish)
  • Recent media feed
  • Media permalinks
  • Account info (username, followers, media count)
  • Linked to Facebook Page

WhatsApp Business whatsapp_api.py — 7 methods

  • Free-form text messages
  • Template messages (pre-approved by Meta)
  • Image messages with caption
  • Document sending (PDF, etc.)
  • Template listing & filtering
  • Account info & phone number
  • Quality rating check

Threads threads_api.py — 13 methods

  • Text posts with reply control
  • Image posts
  • Video posts
  • Thread insights (views, likes, replies)
  • Delete threads
  • Full OAuth flow (auth URL, code exchange, long-lived token, refresh)
  • Account info & permalinks

MCP server: 15 tools for Claude, 4 more behind an opt-in flag

server.py exposes the approval queue and a consolidated set of Facebook Graph API tools. Drop it into Claude Desktop, Claude Code, Cursor, or any MCP-compatible client. Every tool that talks to the Facebook Graph API returns a uniform {"success": bool, "data"|"error": {...}} envelope, so a rate limit or an expired token comes back as an actionable hint, never a raw traceback.

Pipeline and approval queue (11)

Tool What it does
socialblast_status Which AI backends and platforms are configured
socialblast_generate_campaign Generate a 7-day multi-platform campaign into the queue
socialblast_enrich_post Run the AI media pipeline on one pending post
socialblast_enrich_campaign Enrich every pending post in a campaign
socialblast_predict_virality Score a caption's viral potential
socialblast_list_pending List posts awaiting approval
socialblast_create_draft Create a new pending post
socialblast_edit_pending Edit a pending post's fields
socialblast_reject_pending Reject a pending post
socialblast_search_posts Full-text search across the queue
socialblast_queue_stats Counts by status, plus the scheduled queue

None of these tools can approve or publish a post. Approval stays human-only, from the dashboard.

Facebook read-only (4)

Tool What it does
facebook_get_posts Recent Page posts, optionally including scheduled
facebook_get_post_engagement Reactions, comments, shares, permalink, impressions in one call
facebook_get_comments Comments on a post, optionally with reply threads
facebook_get_page_info Extended Page metadata including fan count

🔵 4 direct-write POST tools — opt-in, bypass the approval queue

This is the POST MCP. Set SOCIALBLAST_ALLOW_DIRECT_WRITES=true and these four tools register, letting Claude write to Facebook immediately with no human review step. This is the one place in the project where "no silent automation" is an opt-in you choose, not the default.

Tool What it does
facebook_publish_now POST text or image to your Page immediately, or via Graph's native scheduling
facebook_manage_post Update or delete a live post
facebook_moderate_comment Reply, hide, unhide, or delete one or more comments
facebook_send_dm Send a Messenger DM immediately

Leave the flag unset and the server stays draft-only: every write lands in the approval queue for a human yes. Set it, restart, and facebook_publish_now goes live.

Upgrading from the old 46-tool surface? See the migration table in CHANGELOG.md.

Dashboard — approve everything before it ships

FastAPI + HTMX + Jinja2. No SPA, no Node.js, no build step. SQLite in WAL mode.

Feature How it works
Multi-platform compose Write once, pick Facebook / Instagram / WhatsApp / Threads / LinkedIn
AI compose studio Enhance, rewrite, TTS, captions, video gen, Notion sync. All from the compose toolbar.
AI provider cascade Text AI auto-selects the first available provider: Grok > Bedrock > Ollama
Inline API key management Paste keys in Settings, save and test without restarting
Approval queue Every post lands in pending. Approve, reject, or approve-all
Live publishing Approve > adapter publishes to the real platform API
Toast notifications Success / failure feedback via HX-Trigger events
Settings page Connected accounts, AI service cards, environment overview
OAuth flows Threads, LinkedIn, TikTok, YouTube. Connect with one click.
Connection health Per-platform API health check (token status, account info)
Stats bar Pending / published / failed counts, always visible
Image support Instagram requires image URL; stored per-post in SQLite
WhatsApp templates Pick from Meta-approved templates or send free-form
Recipient field WhatsApp messages route to a specific phone number
Contextual video gen HiggsField auto-derives a video prompt from your post text
HTMX partials Only the changed columns re-render, no full page reload
Favicon Custom SVG favicon served at /favicon.ico

AI services — 7 integrations, all optional

Every AI integration is optional, configured from the Settings page (paste keys, save, test), and stored in ~/.social-auto-engine/tokens.env. No restart needed. The compose studio toolbar surfaces whichever services are configured.

Service What it powers Key
Grok (xAI) Prompt enhancement, post rewriting GROK_API_KEY
Amazon Bedrock Claude for text, SDXL for images, Titan AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY
Ollama Free local LLM fallback (no key needed) OLLAMA_BASE_URL
ElevenLabs Text-to-speech, voice cloning ELEVENLABS_API_KEY
Deepgram Speech-to-text, SRT captions DEEPGRAM_API_KEY
HiggsField / Replicate AI video generation (contextual from post text) REPLICATE_API_TOKEN
Notion Sync drafts to a Notion database NOTION_ACCESS_TOKEN

Text AI cascade. Enhance and rewrite use the first available text provider: Grok > Bedrock > Ollama. Configure one and it works. Configure all three and you have automatic failover.

Contextual video. When you generate a video from the compose studio, the text AI writes a scene prompt from your post content so the video matches what you are publishing.

Content skills — 17 AI workflows

Each skill is a single SKILL.md file in skills/. Drop the folder into any Claude project and trigger by name.

Voice & identity

Skill Trigger What it does
voice-builder "build my voice" Interview + 3-5 writing samples → about-me.md + voice.md
newsletter-voice "build my newsletter voice" Extends voice system to newsletter format with archetype selection
profile-optimizer "optimize my profile" Full LinkedIn rebuild: headline, about, experience, 4 image prompts

Writing

Skill Trigger What it does
post-writer "write a post about X" Drafts in your trained voice using about-me + voice files
post-formatter "format this as PAS" Applies PAS / AIDA / BAB / STAR / SLAY frameworks, 200-250 words
hook-generator "write me hooks" 6 two-line hook variations per topic, digit-heavy, "How I" format
content-matrix "give me post ideas" 32+ ideas from your pillars x 8 formats (Justin Welsh method)
pinned-comment "pinned comment" LinkedIn first-comment + matching image prompt
quote-post "quote post" Motivational quote + Gemini image prompt for the graphic

Visual content

Skill Trigger What it does
graphic-designer "design a graphic" Decides HTML/CSS structured graphic vs AI infographic
gemini-carousel "build a carousel" Slide-by-slide LinkedIn carousel via Gemini, 1080x1350
gemini-infographic "whiteboard infographic" Hand-drawn whiteboard style prompt (480k impressions across 3 posts)
youtube-thumbnail "thumbnail" Branded YouTube thumbnail prompt from video title + reference photo

Research & scoring

Skill Trigger What it does
post-scorer "score my post" Scores draft against your real post performance data via Apify
niche-research "research my niche" Live browser research via Claude for Chrome — Reddit, X, Google
reels-scripting "script a reel" Scrapes reference Reel via Apify, analyses with Gemini, writes your script

Analytics

Skill Trigger What it does
analytics-dashboard "analyse my linkedin" LinkedIn export → interactive React dashboard + strategic analysis

Infrastructure & DX

Feature Details
CI pipeline GitHub Actions — lint + test on every push
Issue templates Bug report + feature request (YAML-based)
PR template Structured checklist for every pull request
.env.example Fully documented — every env var explained with setup links
DEVELOPMENT.md Developer setup guide
CONTRIBUTING.md Contribution rules, branch strategy, code style
MIT license Use it commercially, fork it, ship it
Design system design-system/MASTER.md — color tokens, typography, spacing
Ops guide docs/meta-survival-guide.md — Meta Business Suite token walkthrough
API setup guide docs/api-setup-guide.md — every platform, zero to working token

Roadmap

Feature Status Notes
LinkedIn publishing 🟢 Live Member posting (text, image, article) via UGC API. Connect via /oauth/linkedin/start.
Multi-platform broadcast composer 🟢 Live Compose once, fan out to N selected platforms. Per-platform partial-failure tolerated. (design)
Company-grouped UI 🟢 Live Dashboard sidebar grouped by Meta / LinkedIn / TikTok / YouTube / X.
TikTok publishing 🟡 Code complete, awaiting review Inbox-upload tier (video.upload scope) shipped in tiktok_api.py. Direct-post tier requires full TikTok app review. Connect via /oauth/tiktok/start.
YouTube publishing 🟡 Code complete, awaiting OAuth setup Video upload via Data API v3 in youtube_api.py. Defaults privacyStatus='private' per the no-silent-automation spine. Connect via /oauth/youtube/start.
Scheduler (cron queue) 🟢 Live APScheduler + SQLite jobstore.
AI compose in dashboard 🟢 Live 7 AI services, cascade provider selection, contextual video gen. (#3)
Token auto-refresh helper 🟢 Live Short-lived → long-lived user token exchange and Page-token derivation via scripts/refresh_token.py. (#2)
Provider auth-error surfacing 🟢 Live AI provider 401s now render actionable inline UI instead of raw 500s. (#28)
Empty-state illustrations 🟢 Live First-run empty states for inbox, calendar, and published feeds. (#7)
Landing site (GitHub Pages) 🟢 Live WebGL-animated marketing page at freespirits.github.io/social-auto-engine.
X / Twitter adapter ⚪ Planned Requires Basic tier ($100/mo) or Pro ($5,000/mo). Deferred until usage justifies the spend.
Cross-platform analytics ⚪ Designed Phase 5 of the master plan
Ad boosting (Meta) ⚪ Designed Phase 6 of the master plan

Quick start

1. Run the MCP server (Facebook tools, working now)

git clone https://github.com/Freespirits/social-auto-engine.git
cd social-auto-engine
pip install -r requirements.txt

Create a .env file (see DEVELOPMENT.md and .env.example for the full list):

# Required for posting to Facebook
FACEBOOK_PAGE_ID=your_page_id
FACEBOOK_ACCESS_TOKEN=your_long_lived_page_token

# Unlock 17+ video models via the official HiggsField SDK
# (Seedance 2.0, Kling 2.6, Grok Video, Cinematic Studio, and more)
# Get a key pair at https://cloud.higgsfield.ai/
HF_API_KEY=
HF_API_SECRET=

# Cloned voice narration for AI videos
ELEVENLABS_API_KEY=

# Falls back if HiggsField key pair is missing
REPLICATE_API_TOKEN=

# Premium captions via GPT-4o-mini (optional, falls back to hand-tuned templates)
OPENAI_API_KEY=

Quick sanity check: run python -m dashboard.health to see exactly which backends are configured. No secrets printed, just a green/red status table.

Add to ~/.config/Claude/claude_desktop_config.json (or the Windows equivalent):

{
  "mcpServers": {
    "social-auto-engine": {
      "command": "python",
      "args": ["/absolute/path/to/social-auto-engine/server.py"],
      "env": {
        "FACEBOOK_PAGE_ID": "...",
        "FACEBOOK_ACCESS_TOKEN": "..."
      }
    }
  }
}

Restart Claude Desktop. Try: "Show me my last 5 Facebook posts and their engagement."

2. Use the skills (any Claude project)

Drop the skills/ folder into a Claude project, then say:

  • "build my voice" → walks you through the voice profile interview
  • "write a post about X" → drafts in your voice with a chosen framework
  • "score my post" → rates a draft against your real top performers
  • "script a reel" → reverse-engineers a reference reel and writes yours

Each skill is a single SKILL.md file. Read it, edit it, fork it.

Architecture in one picture

                 ┌──────────────────────────────────────────┐
                 │   Dashboard (FastAPI + HTMX + SQLite)    │
                 │   localhost:7651                         │
                 │   compose · inbox · settings · calendar  │
                 └──────────────────────────────────────────┘
                          │                    │
        ┌─────────────────┤                    │
        ▼                 ▼                    ▼
  ┌──────────┐    ┌─────────────┐    ┌───────────────────┐
  │ Approval │    │  Scheduler  │    │   AI Services     │
  │  Queue   │    │ (APSched)   │    │  Grok · Bedrock   │
  └──────────┘    └─────────────┘    │  Ollama · 11Labs  │
        │                │           │  Deepgram · Repl.  │
        │                │           │  Notion            │
        │                │           └───────────────────┘
        └────────────────┤
                         ▼
          ┌────────────────────────────────────┐
          │         Platform Adapters          │
          │  FB · IG · WA · Threads · LinkedIn │
          │  TikTok · YouTube (in review)      │
          └────────────────────────────────────┘

Full breakdown — including SQL schemas, dashboard wireframes, AI provider routing, batch workflows for 100 pages, and the 6-phase roadmap — lives in docs/specs/2026-05-02-multi-channel-platform-master-plan.md.

Help wanted

This project is the size where one weekend from the right person changes the trajectory. Here's where you can pick up a meaningful chunk:

🎯 High-impact, ready to start

Area What Skills needed Issue
X / Twitter adapter Mirror instagram_api.py shape for X posting Python, OAuth 2.0 Requires Basic tier ($100/mo)
Docker setup docker-compose for dashboard + dependencies Docker, Docker Compose —
Dashboard auth Cookie-based password auth (in flight on dashboard-addons) Python, FastAPI —
Cross-platform analytics Unified metrics across FB, IG, Threads, LinkedIn Python, charting Phase 5 of master plan
TikTok app review Submit for direct-post tier (video.publish scope) Process, screencast —
YouTube OAuth consent Submit verification for Data API v3 publish scope Process, app verification —

✅ Recently shipped

Area Status
Landing site WebGL-animated marketing page on GitHub Pages at freespirits.github.io/social-auto-engine.
Token refresh helper Short-lived → long-lived exchange + Page-token derivation via scripts/refresh_token.py. #2
Provider auth-error UI AI provider 401s now render actionable inline messages instead of raw 500s. #28
Empty-state illustrations First-run empty states for inbox, calendar, and published feeds. #7
LinkedIn adapter Live. Member posting (text, image, article) via UGC API. #5
Test suite 190+ tests. DB, dashboard, adapters, AI services. #6
AI compose 7 AI services, cascade provider selection, contextual video gen. #3
Scheduler APScheduler + SQLite jobstore. #4

🧪 Solid second-tier

  • TikTok direct-post tier (code complete, awaiting full app review)
  • YouTube publishing (code complete, awaiting OAuth consent screen)
  • Documentation: per-skill docs, architecture decision records
  • Additional AI providers (OpenAI, Gemini) as cascade options

💡 Got a different idea?

Open an issue with the label proposal. The master plan is the north star but it's not law — if you have a sharper take, make the case.

🔗 Standing on shoulders

We've curated 24 open-source projects that can accelerate this work. See docs/integrations.md. Top picks: Postiz (provider abstraction reference), CRUDAdmin (FastAPI+HTMX admin), python-statemachine (proper post lifecycle modeling).

How to contribute

  1. Read the master plan. Even a skim. It's the contract.
  2. Open an issue describing what you want to build before you write code. Saves rework.
  3. Branch from main, small focused PRs. One adapter per PR is fine.
  4. No silent automation. If your change adds a write action, it must go through the approval queue or be opt-in with a warning. This is the project's spine.
  5. British English in user-facing copy. No em dashes. Yes, even in PR descriptions. (You'll see why once you read voice.md.)

Tech stack

  • Python 3.11+ — server, adapters, content pipeline
  • MCP (Model Context Protocol) — tool layer, integrates with Claude / Cursor / any MCP client
  • FastAPI + HTMX + Jinja2 — dashboard (no SPA build step, no Node.js dependency)
  • SQLite (WAL mode) — single-file persistence, zero ops
  • APScheduler — cron-driven scheduled publishing with SQLite jobstore
  • Apify — Instagram / LinkedIn scraping for trend research and post-history scoring
  • AI providers — Grok (xAI), Amazon Bedrock (Claude, SDXL), Ollama (local), ElevenLabs, Deepgram, HiggsField/Replicate, Notion

Project origins

SocialBlast AI merges two open-source projects:

Both still stand on their own. This repo is the integration: the MCP backbone meets the content pipeline meets a multi-channel dashboard.

License

MIT. Use it, fork it, ship it commercially. Just don't pretend you wrote it from scratch — credit lives in LICENSE and the origin links above.