Social Auto Engine

---

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

The open-source operating system for your social media.

Buffer + Jasper, but you actually own it. Write once, publish to Facebook, Instagram, Threads, WhatsApp, and LinkedIn from a single dashboard. TikTok and YouTube adapters live in the codebase, awaiting their developer-app reviews. X is on the roadmap behind its paid API tier. AI drafts in your voice. You approve every post. The system publishes it. Scales from one personal page to one hundred client accounts.

🚀 git clone • pip install • python -m dashboard.app → http://127.0.0.1:7651 • You're posting in 5 minutes.

---

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 6 new MCP tools on top of the existing 37: 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 37-tool MCP server into Claude Desktop or Claude Code. Read tools work immediately. Write tools land in your local approval queue.

Five-minute MCP setup →

---

What it looks like

10-second walkthrough: Inbox → Calendar → Published → Settings. Auto-plays on supporting browsers, or download the MP4.

The hero — bold typography over a soft mesh background. Marketing site at freespirits.github.io/social-auto-engine.

AI video tiles — four HiggsField clips in IG, Threads, YouTube, and Facebook aspect ratios. The compose studio drops them straight into the approval queue.

Help wanted — token refresh, X adapter, Docker setup, cross-platform analytics. One weekend from the right person changes the trajectory.

📺 Marketing site: freespirits.github.io/social-auto-engine • Live dashboard: HF Space

---

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 — 37 tools for Claude

server.py exposes every adapter method as an MCP tool. Drop it into Claude Desktop, Claude Code, Cursor, or any MCP-compatible client.

All 37 tools (click to expand)

Publishing | Tool | What it does | |---|---| | post_to_facebook | Text post to your Page | | post_image_to_facebook | Image + caption post | | schedule_post | Schedule a post for future publish time | | update_post | Edit an existing post's message | | delete_post | Remove a post from the Page | | send_dm_to_user | Direct message a user |

Comments | Tool | What it does | |---|---| | reply_to_comment | Reply to a specific comment on a post | | get_post_comments | Retrieve all comments on a post | | get_comment_replies | Get reply thread on a comment | | get_number_of_comments | Count comments on a post | | get_post_top_commenters | Ranked list of most active commenters | | delete_comment | Delete a comment | | delete_comment_from_post | Delete by post + comment ID | | hide_comment | Hide from public view | | unhide_comment | Restore a hidden comment | | bulk_delete_comments | Delete multiple comments at once | | bulk_hide_comments | Hide multiple comments at once | | bulk_unhide_comments | Unhide multiple comments at once | | filter_negative_comments | Basic negative sentiment filter |

Analytics & insights | Tool | What it does | |---|---| | get_post_insights | All metrics for a post (impressions, reactions, clicks) | | get_post_impressions | Total impressions | | get_post_impressions_unique | Unique impressions | | get_post_impressions_paid | Paid impressions | | get_post_impressions_organic | Organic impressions | | get_post_engaged_users | Users who engaged | | get_post_clicks | Click count | | get_number_of_likes | Like count | | get_post_share_count | Share count | | get_post_reactions_breakdown | All reaction types in one call | | get_post_reactions_like_total | Like reactions | | get_post_reactions_love_total | Love reactions | | get_post_reactions_wow_total | Wow reactions | | get_post_reactions_haha_total | Haha reactions | | get_post_reactions_sorry_total | Sad reactions | | get_post_reactions_anger_total | Angry reactions |

Page management | Tool | What it does | |---|---| | get_page_posts | Recent posts on the Page | | get_page_fan_count | Total fans / likes | | get_page_info | Extended Page metadata | | get_post_permalink | Permanent URL of a post | | get_scheduled_posts | All unpublished scheduled posts |

---

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 |

10-second walkthrough: Inbox → Calendar → Published → Settings.

---

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.

All 17 skills (click to expand)

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](docs/specs/2026-05-06-company-grouped-ui-and-multi-platform-compose-design.md)) | | 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

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Freespirits
• Source: Freespirits/social-auto-engine
• License: MIT

Install and usage instructions live in the source repository linked above.