SocialMCP

Unified Model Context Protocol (MCP) server for YouTube, TikTok, Instagram, and Threads.

It extracts video and post metadata, creator feeds, comments, direct media streams, and full transcripts. For videos without captions or videos made of screenshots and text slides, SocialMCP combines local Faster-Whisper audio transcription with keyframe & carousel OCR (ffmpeg + Pillow + Tesseract).

What it does

• TikTok (no API key or login needed): video and photo-carousel metadata, view/like/comment/share/save counts, creator feeds, closed captions, Whisper audio transcription, and OCR for screenshot videos and slide carousels.

• Instagram (no API key needed; anonymous embed fallback included): Reels, photo posts, multi-slide carousels, creator feeds, direct CDN links, Whisper speech transcription, and OCR for screenshot Reels and image slides.

• Threads (no login needed): post content, replies/comments, topic/hashtag search, creator feeds, direct media links, and optional video/image transcription.

• YouTube:

  • Transcripts and caption tracks work without any API key (multi-tier caption fetcher + Whisper + keyframe OCR fallback).

  • Search, batch video details, and playlist management use the YouTube Data API v3 (OAuth credentials optional, only needed for these tools).

Related MCP server: Video Transcriber MCP Server

System requirements

• Python 3.11+

• ffmpeg (for audio extraction and video keyframe sampling)

• tesseract with Russian and English language packs (tesseract-ocr, tesseract-ocr-rus, tesseract-ocr-eng) for transcribing screenshots and on-screen text

Installing system dependencies

macOS (Homebrew):

brew install ffmpeg tesseract tesseract-lang

Ubuntu / Debian:

sudo apt update && sudo apt install -y ffmpeg tesseract-ocr tesseract-ocr-rus tesseract-ocr-eng

Quick start (local stdio)

You can run SocialMCP directly with uvx without cloning the repository. Add this to your MCP client configuration (claude_desktop_config.json, Cursor, Windsurf, or Antigravity mcp_config.json):

{
  "mcpServers": {
    "social": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/bledny1099/social-mcp.git",
        "social-mcp"
      ]
    }
  }
}

Or install it into a local environment with pip / uv:

git clone https://github.com/bledny1099/social-mcp.git
cd social-mcp
pip install -e .
social-mcp --transport stdio

Self-hosting via Docker (remote HTTP MCP)

SocialMCP also runs as a remote Streamable HTTP server with Bearer token authentication and OAuth 2.1 support (compatible with Claude web/mobile connectors).

git clone https://github.com/bledny1099/social-mcp.git
cd social-mcp
cp .env.example .env
# Edit .env and set MCP_BEARER_TOKEN (e.g. openssl rand -hex 32)
docker compose up -d --build

The server listens on 127.0.0.1:8087 (mapped to container port 8080, path /mcp). Put Nginx or Caddy in front of it with TLS (see Caddyfile.snippet).

Available MCP tools (18)

TikTok

Instagram

Threads

YouTube

How screenshot and slide video transcription works

Short-form videos on TikTok, Reels, and Shorts often have background music instead of speech while showing screenshots, chat logs, or text slides on screen.

When tiktok_get_transcript, instagram_get_transcript, or youtube_get_transcript runs:

1. If the post is an image carousel or photo-mode slideshow, SocialMCP downloads the slides concurrently and runs OCR on each image.

2. If the post is a video, ffmpeg extracts scene changes and time-spaced keyframes.

3. Consecutive frames are compared using a 256-bit perceptual difference hash on the central 80% region (ignoring animated corner watermarks) so identical frames are skipped before OCR.

4. Pillow checks frame luminance, inverts dark-mode screenshots so white-on-dark text becomes sharp black-on-white, applies contrast normalization, and passes the result to tesseract (rus+eng) in TSV mode.

5. Low-confidence noise tokens are filtered out, scrolling screenshots are deduplicated line-by-line across frames, and the extracted on-screen text is merged with the Whisper speech transcript.

Optional YouTube Data API setup

You only need Google OAuth credentials if you want to use youtube_search, youtube_get_videos, or the playlist tools (youtube_get_transcript works without them).

1. Create a project in Google Cloud Console and enable YouTube Data API v3.

2. Create OAuth 2.0 Web Application credentials and add http://localhost:8765/ to Authorized redirect URIs.

3. Run the local helper script to get your refresh token:

   python scripts/get_refresh_token.py --client-id YOUR_ID --client-secret YOUR_SECRET

4. Paste YT_CLIENT_ID, YT_CLIENT_SECRET, and YT_REFRESH_TOKEN into .env.

Environment variables

License

MIT