What is this?

A social media trends aggregator that works in two modes:

1. MCP Server — Plug into Claude Desktop, Cursor, or any MCP client. Ask trending questions in natural language.
2. REST API — Self-hosted API service with auto-refresh every 6 hours, PostgreSQL storage, and WebSocket push.

Supported Platforms

| Platform | Method | API Key Required? | |----------|--------|-------------------| | 🎬 YouTube | Data API v3 | ✅ Free (10K units/day) | | 🎵 TikTok | Creative Center API | ❌ No | | 🐦 X (Twitter) | Web scraping fallback | ❌ No (API optional, $200/mo) | | 📸 Instagram | Meta Graph API + fallback | ❌ No (API optional) |

Every scraper has multi-level fallback — if one method fails, it automatically tries the next.

⚡ Quick Start

Use as MCP Server (recommended)

Claude Desktop — Add to claude_desktop_config.json:

{
  "mcpServers": {
    "social-trends": {
      "command": "uvx",
      "args": ["social-trends-mcp"],
      "env": {
        "YOUTUBE_API_KEY": "your_youtube_api_key"
      }
    }
  }
}

Then just ask:

• "What's trending on YouTube right now?"
• "Show me TikTok trends"
• "Is AI trending on any social platform?"
• "Give me a full overview of what's trending globally"

Install from source

git clone https://github.com/YOUR_USERNAME/social-trends-mcp.git
cd social-trends-mcp
pip install -e .
python mcp_server.py

🔧 MCP Tools

| Tool | Description | |------|-------------| | get_trends | Get trending topics from a specific platform (twitter, tiktok, youtube, instagram) | | get_all_trends | Get trends from ALL platforms at once | | search_trends | Search for a keyword across all platform trends |

Example: get_trends

Input:  { "platform": "youtube", "limit": 10 }
Output: Ranked list of trending videos with view counts and URLs

Example: search_trends

Input:  { "query": "AI" }
Output: All trending topics mentioning "AI" across every platform

🌐 REST API

For production use, deploy the full API service with PostgreSQL and auto-refresh.

| Method | Path | Description | |--------|------|-------------| | GET | /api/v1/trends | All platforms latest data | | GET | /api/v1/trends/{platform} | Single platform trends | | GET | /api/v1/trends/history/{platform} | Historical trends | | POST | /api/v1/refresh | Manual refresh trigger | | GET | /api/v1/health | Service health + stats | | GET | /docs | Interactive Swagger UI | | WS | /ws/trends | WebSocket real-time push |

🐳 Docker Deployment

Full production stack in one command:

git clone https://github.com/YOUR_USERNAME/social-trends-mcp.git
cd social-trends-mcp
cp .env.example .env
# Edit .env — at minimum set YOUTUBE_API_KEY

docker-compose up -d

This starts PostgreSQL + App (4 workers) + Nginx.

⚙️ Configuration

| Variable | Required | Description | |----------|----------|-------------| | YOUTUBE_API_KEY | Recommended | Get free — 10K units/day | | TWITTER_BEARER_TOKEN | Optional | $200/mo — fallback works without it | | INSTAGRAM_ACCESS_TOKEN | Optional | Meta Developer — fallback works without it | | TIKTOK_PROXY | Optional | Proxy URL if TikTok blocks your IP | | SCRAPE_INTERVAL_HOURS | Optional | Auto-refresh interval (default: 6) |

Zero-config is possible — every platform has fallback scrapers that work without API keys.

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md.

Easy wins: Add a new platform (Threads, Bluesky...), improve scraper quality, add MCP tools, translations.

📄 License

MIT