Social-Ops

Open-source social-media intelligence platform for AI agents. Wire it into Claude Code / Cursor / Continue / any MCP-compatible client and your agent gains topic-aggregation reports across Reddit, Instagram, Facebook, X, App Store and Google Play — backed by a SaaS-style web console for browsing reports, tracking jobs, and managing credentials.

Two services, two ports:

No LLM is required. Reports are produced by a deterministic NLP pipeline (TF-IDF / sentence-transformers clustering + lexicon / XLM-RoBERTa sentiment).

Quickstart

git clone <this repo>
cd social-ops
cp .env.example .env
docker compose up -d
open http://localhost:8088

The console will detect that no required keys are configured and walk you through a 5-step wizard to enter Reddit + Apify credentials (free / freemium), then optionally Instagram + X session cookies. After docker compose restart mcp the MCP server picks up the new env, and you can wire your agent into the endpoint shown on the Connect tab.

For Claude Code:

claude mcp add --transport http social-ops http://localhost:8097/mcp

Then in any session: "Analyze the r/python subreddit and tell me what people are discussing this month."

What it does

The MCP server exposes 16 tools, organized in three groups:

Collection / analysis (async — return a task_id)

Task & report inspection (instant)

Utility

• search_app — find Google Play / App Store bundle IDs before analyzing
• help — per-tool docs (token-efficient progressive disclosure)

Report shape (what your agent gets back)

Pure topic-aggregation, no prescriptive analysis. Each report contains:

• Overview — doc count, topic count, sentiment distribution, coverage
• Topics (one block per cluster) — discussion count, share %, sentiment breakdown, top key terms, top subreddits/accounts, monthly volume, representative quote, 4–6 cited evidence snippets
• Time Trend — monthly doc + sentiment counts
• Data Quality — confidence, uncertainty flags
• Method Card — collection / indexing / clustering / sentiment models
• Citations — full index, every cited source linkable

Reports are stored at data/cache/<platform>/reports/<handle_id>.{md,json} and surfaced via the console at http://localhost:8088/reports.

Architecture

┌────────────────┐   HTTP      ┌────────────────┐
│  Your Agent    │────────────▶│   mcp:8097     │ Streamable-HTTP MCP
│ (Claude/Cursor)│             │  (FastMCP)     │ + REST /api/*
└────────────────┘             └───┬────────────┘
                                   │ subprocess
                                   ▼
        ┌──────────────────────────────────────────┐
        │  tools/                                  │
        │   ├─ reddit-ops/   (Node, OAuth)         │
        │   ├─ social-ops/   (Python, Apify+xreach)│
        │   ├─ google-play-scraper/   (Node CLI)   │
        │   └─ app-store-scraper/     (Node CLI)   │
        └──────────────────────────────────────────┘
                                   │
        ┌──────────────────────────▼───────────────┐
        │  data/cache/{reddit,social-ops}/         │
        │  (collection JSONL / index / analysis /  │
        │   reports / cost log)                    │
        └──────────────────────────────────────────┘
                  ▲
                  │  /api/reports, /api/tasks
                  │
       ┌──────────┴──────────┐
       │  console:8088       │ React + Vite + Tailwind
       │  (FastAPI + SPA)    │ → 6 languages, no auth in core
       └─────────────────────┘

Pipeline per platform: collect → embed/index → aggregate → report. Each stage is a standalone CLI under tools/; the MCP server orchestrates them as background subprocesses, persists outputs to data/cache/, and the console reads them back via the MCP REST API.

Repo layout

.
├── docker-compose.yml          # Two services: mcp + console
├── .env.example                # Copy to .env, fill via console
├── services/
│   ├── mcp/                    # FastMCP server (Python, FastAPI, FastMCP)
│   └── console/                # React+Vite SPA + FastAPI backend
│       ├── app/                # Backend: providers, routers, env_store
│       └── web/                # Frontend: pages, components, i18n locales
└── tools/
    ├── reddit-ops/             # Node — Reddit OAuth pipeline (v2)
    ├── social-ops/             # Python — Instagram/Facebook/X/App-store
    ├── google-play-scraper/    # Node — google-play-scraper CLI wrapper
    └── app-store-scraper/      # Node — app-store-scraper CLI wrapper

Configuration

All credentials are managed via the console's Settings → Providers tab (or directly in .env if you prefer). Each provider has a built-in guide explaining where to find the keys and a live "Test connection" button.

Google Play review analysis works without any credentials.

.env is .gitignore'd. Test credentials never leave your machine — the console only contacts a provider when you click Test connection.

UI

Available in English / 中文 / 日本語 / 한국어 / Français / Deutsch (switch from the header dropdown; preference persists in localStorage).

• /reports — searchable / platform-filterable report library, KPI tiles
• /reports/:handle_id — full markdown report with sentiment bar + topic chips
• /tasks — live task table, auto-refresh every 5s
• /settings — sub-tabs:
  • Providers — credential cards with live validators + per-provider guide
  • Connect — MCP endpoint URL + copy-paste install snippets for Claude Code / Claude Desktop / Cursor / Continue.dev / custom HTTP
  • About — system info

Security

The core ships without authentication. This is intentional — the console binds to 127.0.0.1:8088 and the MCP server to 127.0.0.1:8097 by default, expecting a single-user, single-machine deployment.

If you want to expose either service to the network or the internet, add your own authentication via:

• A reverse proxy (nginx / Caddy / Cloudflare Tunnel with Access)
• Tailscale or similar mesh VPN — limits exposure to your devices
• An OAuth proxy (oauth2-proxy, etc.) in front of the console

Pull requests that add auth as a hard project dependency will be declined; keeping the core unopinionated about deployment is a design goal.

Report security issues privately — see SECURITY.md when present, or open a private GitHub Security Advisory.

Development

Running the console frontend in dev mode

cd services/console/web
npm install
npm run dev    # Vite on :5173, proxies /api/* to :8088

The Vite dev server proxies /api/* to the running console container, so you get live HMR while still hitting the real backend.

Running collection scripts directly

Each tool ships as a standalone CLI:

# Reddit (after `cp .env.example .env` + filling REDDIT_*)
cd tools/reddit-ops
bash install.sh
node reddit-collect.mjs --subs "python,LocalLLaMA" --window 30d

# Instagram via Apify
cd tools/social-ops
bash install.sh
python3 insta_collect_apify.py --accounts "nike" --window 7d --max_posts 10

See each tool's README for full flag documentation.

License

MIT — see LICENSE.

Acknowledgements

Built on top of FastMCP, FastAPI, React + Vite, Instaloader, the Apify ecosystem, xreach-cli, and the google-play-scraper / app-store-scraper libraries.

For the full dependency list with licenses, see THIRD_PARTY_NOTICES.md.