115 lines
3.8 KiB
Markdown
115 lines
3.8 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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.*
|