socialmag/MANIFEST.md

socialmag — Social Media MCP Server

One tool, all platforms. Post to Threads, Facebook, Instagram, TikTok (and YouTube when eligible) through a single MCP call. Built on CDP — no API keys, no rate limits, no approval process. Just a browser and a logged-in account.

What It Does

• create_post — Post text/media to one or more platforms in one call
• check_login — Verify which platforms are logged in
• get_status — Last post results + open browser tabs

Architecture

Claude/MCP Client
    ↓ stdio (JSON-RPC)
socialmag server.py
    ↓ CDP WebSocket
Brave Browser (dedicated instance, port 9336)
    ↓ real browser sessions
Threads · Facebook · Instagram · TikTok · YouTube

• Tab reuse — attaches to existing tabs, no cold loads
• Per-platform modules — each platform has its own flow + selectors
• Sequential queue — one platform at a time, no race conditions
• Error screenshots — failed flows capture the page state to /tmp/socialmag/

Platform Status

Platform	Text	Media	Tab Reuse	Status
Threads	✅	🔲	✅	Live — inline composer
Facebook	✅	🔲	✅	Live — dialog flow
Instagram	—	✅	✅	Live — media required
TikTok	—	✅	✅	Live — video/photo upload
YouTube	🔲	🔲	✅	Parked — needs 500 subs

✅ = tested live · 🔲 = coded but untested · — = not applicable

Stack

• Python 3 (stdlib + websockets)
• Chrome DevTools Protocol (CDP)
• MCP stdio transport
• Brave Browser with --remote-debugging-port

Browser Setup

# Dedicated Brave instance (separate profile, no interference)
brave --remote-debugging-port=9336 \
      --user-data-dir=$HOME/.local/share/brave-socialmag \
      --disable-features=BeforeUnloadDialog \
      --mute-audio --no-first-run

Log into each platform manually once. socialmag reuses those sessions.

Future Roadmap

v0.2 — Read Side

• get_notifications(platform) — pull notifications via CDP scraping
• get_comments(platform, post_id?) — read comments on recent posts
• get_engagement(platform) — likes, shares, reach per post

v0.3 — Monitoring

• Cron/loop polling — periodic checks, dump to JSON
• Unified notification feed across all platforms
• Alert on new comments/DMs

v0.4 — Dashboard

• Web dashboard — one view for all platform activity
• Post scheduler — queue posts for specific times
• Analytics — engagement trends, best posting times

v0.5 — Media Pipeline

• Threads media posting (image + video)
• Facebook media posting
• YouTube video upload (separate from community posts)
• Auto-resize/format media per platform requirements

Later

• Multi-account support
• Platform API integration (where available + worthwhile)
• Content calendar
• AI-assisted caption generation

File Structure

socialmag/
├── __init__.py       # package marker
├── __main__.py       # python -m socialmag entry
├── server.py         # MCP stdio server + tool handlers
├── cdp.py            # CDP WebSocket client
├── selectors.py      # all platform selectors in one file
├── queue.py          # sequential post queue
├── platforms/
│   ├── __init__.py   # shared helpers (guard, require_media, etc.)
│   ├── threads.py
│   ├── facebook.py
│   ├── instagram.py
│   ├── tiktok.py
│   └── youtube.py
└── MANIFEST.md       # this file

License

Private. Shared among collaborators by invitation.

---

Born 2026-09-10. Built by the household — Celeste architected, Umbra built the skeleton, abang drove the FAFO.