sSmcp
Provides tools to fetch Instagram Reels, posts, and carousel metadata, captions, counts, and media URLs; transcribe spoken audio and OCR on-screen text; and list public user posts.
Provides tools to fetch Threads posts with engagement metrics and top replies, search public posts by keyword, list author feeds, and transcribe or OCR attached video/image media.
Provides tools to fetch TikTok video metadata, batch inspect videos, extract native captions or Whisper/OCR transcripts, list public user videos, and download/publish watermark-free videos and covers.
Provides tools for searching YouTube videos, channels, and playlists; inspecting video metadata; managing playlists; and extracting transcripts via captions or Whisper/OCR fallback, with YouTube Data API quota tracking.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@sSmcpgrab the transcript and on-screen text from this TikTok"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Overview
sSmcp connects your AI assistant (Claude Desktop, Cursor, Antigravity IDE, Windsurf, Claude Code, etc.) directly to YouTube, TikTok, Instagram, and Threads through a single MCP server. It pulls video metadata, author statistics, comments, spoken audio transcripts, and on-screen text from screenshots and photo carousels into your workspace.
TikTok, Instagram, Threads, and YouTube transcripts work immediately with zero API keys required.
Key capabilities
4 platforms in 1 server (20 tools): Full coverage of YouTube, TikTok, Instagram, and Threads without running separate background services.
Multi-tier extraction with fallback: Extracts video metadata, view counts, and direct streams via
yt-dlp, with automatic fallback to platform-specific APIs (tikwmandembed/v2for TikTok, HTML parsers for Instagram and Threads,youtube-transcript.aiandLemnosLifefor YouTube) when anti-bot challenges trigger.Local speech-to-text: Fast speech transcription powered by
faster-whisper(int8on CPU by default). Runs locally on your machine or VPS without external cloud speech billing.Visual OCR for screenshots and slides: Automatically extracts keyframes from videos (
ffmpegscene-change detection and interval sampling), deduplicates identical frames with a 256-bit center-cropdHash, preprocesses dark-mode and light-mode text withPillow, and runstesseract(rus+engby default) to read slides, chat logs, code snippets, and photo carousels.Whisper hallucination filtering: Strips repeating subtitle loops caused by background music on videos without human speech.
Outbound proxy and cookie support: Native HTTP and SOCKS5 proxy routing (
SSMCP_PROXY) andcookies.txthandling to bypass geo-restrictions and rate limits.Custom domain publishing: Download media and host watermark-free
.mp4video and.jpgcover assets directly on your own server or CDN.Flexible transports and authentication: Supports local
stdiomode for desktop clients, as well ashttpandssemodes with static Bearer tokens or built-in OAuth 2.1 (Google Sign-In and password login).
Related MCP server: Social → Context
Available Tools
The server registers 20 tools across all four supported platforms.
TikTok Tools (No API Key Required)
Tool | Parameters | Description |
|
| Returns post title, description, hashtags, links, author stats, view/like/share counts, cover image, and carousel items. |
|
| Fetches metadata for up to 20 TikTok links concurrently with a single call. |
|
| Returns native TikTok captions when available, or runs local Faster-Whisper and keyframe/slide OCR. Returns combined text, separate audio text, and on-screen OCR text. |
|
| Lists recent videos from a public |
|
| Downloads video ( |
Instagram Tools (No API Key Required)
Tool | Parameters | Description |
|
| Fetches caption, author, like and comment counts, duration, and direct media URLs for Reels, posts, and multi-slide carousels. |
|
| Transcribes spoken audio in Reels with Faster-Whisper and reads on-screen text from video keyframes or carousel slides with Tesseract OCR. |
|
| Fetches recent public posts and Reels from an Instagram |
Threads Tools (No API Key Required)
Tool | Parameters | Description |
|
| Fetches a Threads post, engagement metrics, top replies, and optionally transcribes and runs OCR on attached videos or images. |
|
| Searches public Threads posts by keyword. |
|
| Lists recent posts and replies from a public Threads |
YouTube Tools
Tool | Parameters | Description | Needs API Key? |
|
| 4-tier transcript extraction ( | No |
|
| Lists available manual and auto-generated subtitle tracks for a video. | No |
| (none) | Returns daily YouTube Data API v3 quota usage and remaining units. | No |
|
| Searches YouTube for videos, channels, or playlists. | Yes ( |
|
| Batch lookups for up to 50 video IDs with views, likes, comments, and duration. | Yes ( |
|
| Lists playlists for a channel or the authenticated account. | Yes (API key or OAuth) |
|
| Lists videos inside a playlist with playlist item IDs for management. | Yes (API key or OAuth) |
|
| Adds a video to a playlist. | Yes (OAuth) |
|
| Removes an entry from a playlist by item ID. | Yes (OAuth) |
Language handling
The languages parameter controls Whisper speech recognition and Tesseract OCR:
Value | Behavior |
| Locks Whisper to Russian and prioritizes Russian + English in Tesseract OCR. |
| Runs Whisper in multilingual mode covering code-switched speech and bilingual |
| Whisper auto-detects spoken language; OCR defaults to |
Installation and Setup
Prerequisites
Python 3.10 or higher
ffmpeg(required for audio extraction and keyframe sampling)tesseract-ocrwith Russian and English language packs (required for visual OCR)
# macOS
brew install ffmpeg tesseract tesseract-lang
# Ubuntu / Debian
sudo apt-get update && sudo apt-get install -y ffmpeg tesseract-ocr tesseract-ocr-rus tesseract-ocr-eng1. Clone repository
git clone https://github.com/bledny1099/sSmcp.git
cd sSmcp2. Install dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install .3. Configure environment (optional)
cp .env.example .envTikTok, Instagram, Threads, and YouTube transcripts work without any API keys. If you want remote access, YouTube search, or custom publishing, edit .env:
SSMCP_TRANSPORT=http
SSMCP_PORT=8890
SSMCP_BEARER_TOKEN=your_secure_random_token_here
SSMCP_WHISPER_MODEL=small
SSMCP_OCR_LANGUAGES=rus+eng4. Pre-download the Whisper model (recommended)
Pre-downloading prevents the first transcription call from waiting on model weights:
.venv/bin/python scripts/download_model.py small5. Run server
Option A: Local stdio (for IDEs and Desktop clients)
.venv/bin/ssmcpOption B: HTTP or SSE daemon (for remote server deployments)
export SSMCP_TRANSPORT=http
.venv/bin/ssmcpThe HTTP transport binds to 127.0.0.1:8890 by default. Put it behind a reverse proxy (Caddy or Nginx) when deploying remotely.
Configuration Reference
All settings are configured through environment variables. Every variable has a sensible default.
Transport
Variable | Default | Description |
|
|
|
|
| Bind address in HTTP/SSE mode. Keep on loopback behind a reverse proxy. |
|
| Bind port in HTTP/SSE mode. |
Authentication (Remote HTTP/SSE Mode)
Variable | Default | Description |
| (empty) | Static token for |
| (auto) | Public HTTPS base URL (e.g. |
| (empty) | Password for the built-in OAuth 2.1 login screen. |
| (empty) | Google OAuth Client ID for OAuth 2.1 login. |
| (empty) | Google OAuth Client Secret for OAuth 2.1 login. |
| (empty) | Comma-separated email whitelist for Google Sign-In. |
Network and Scraping
Variable | Default | Description |
| (empty) | HTTP or SOCKS5 proxy URL (e.g. |
| (empty) | Path to a Netscape-format |
Transcription and Visual OCR
Variable | Default | Description |
|
| Faster-Whisper model: |
|
| Inference device: |
|
| Precision: |
|
| Directory for caching Whisper model weights. |
|
| Maximum video length in seconds accepted for Whisper fallback. |
|
| Enable Tesseract OCR for video keyframes and image carousels. |
|
| Tesseract language pack string (e.g. |
|
| Maximum keyframes sampled per video. |
Media Publishing (tiktok_publish_video)
Variable | Default | Description |
|
|
|
| none | Local folder served by Nginx or Caddy. |
| none | Public URL prefix returned for uploaded assets. |
| none | Remote host for SCP upload mode. |
|
| SSH port for SCP mode. |
|
| SSH user for SCP mode. |
| none | Path to private SSH key for SCP mode. |
| none | Destination folder on remote server in SCP mode. |
YouTube Data API v3 (Optional)
Variable | Default | Description |
| (empty) | API key for |
| (empty) | Google OAuth Client ID for playlist management tools. |
| (empty) | Google OAuth Client Secret for playlist management tools. |
| (empty) | OAuth refresh token (generate via |
|
| Daily API quota cap before requests are paused. |
|
| Quota warning threshold. |
|
| Path where daily quota ledger is persisted. |
Resource requirements
Whisper Model | Approx. RAM | Speed on CPU | Best Use Case |
| ~1.5 GB | Fast (~2-3x real time) | General production, short videos, Reels, TikToks |
| ~0.7 GB | Very fast | Low-memory VPS instances (1-2 GB RAM) |
| ~4.0 GB | Roughly real time | Complex multi-speaker speech with noisy backgrounds |
Media Hosting and Downloads
When calling tiktok_publish_video, the server downloads the watermark-free video and cover thumbnail and makes them accessible under your own domain.
Option 1: Local Directory Mode (Self-Hosted on Same Server)
Point a directory served by Caddy or Nginx:
SSMCP_UPLOAD_MODE=local
SSMCP_UPLOAD_LOCAL_DIR=/var/www/uploads
SSMCP_UPLOAD_PUBLIC_URL_PREFIX=https://cdn.yourdomain.com/uploadsEnsure the user running ssmcp has write permissions:
sudo chown ssmcp:www-data /var/www/uploads
sudo chmod 0755 /var/www/uploadsOption 2: Remote SCP Mode (Upload to a CDN or Storage Host)
If sSmcp runs on an application server and static assets live on another machine:
SSMCP_UPLOAD_MODE=scp
SSMCP_UPLOAD_SSH_HOST=cdn.yourdomain.com
SSMCP_UPLOAD_SSH_PORT=22
SSMCP_UPLOAD_SSH_USER=deploy
SSMCP_UPLOAD_SSH_KEY=/home/ssmcp/.ssh/id_ed25519
SSMCP_UPLOAD_REMOTE_DIR=/var/www/uploads
SSMCP_UPLOAD_PUBLIC_URL_PREFIX=https://cdn.yourdomain.com/uploadsSecurity and Authentication
When running in HTTP or SSE mode on a remote server, protect the instance from unauthorized access. An open instance allows arbitrary video downloads, OCR processing, and Whisper inference on your CPU.
Rules
Keep
SSMCP_HOST=127.0.0.1. Never expose port8890directly to the public internet.In Docker, always bind ports to localhost:
-p 127.0.0.1:8890:8890.Set
SSMCP_BEARER_TOKENwith a strong token (openssl rand -hex 24).Terminate TLS and check the token at your reverse proxy (Caddy or Nginx).
Keep
.envandcookies.txtout of version control.
Nginx Configuration
map $http_authorization $mcp_ok {
default 0;
"Bearer YOUR_SSMCP_BEARER_TOKEN" 1;
}
server {
listen 443 ssl http2;
server_name mcp.yourdomain.com;
ssl_certificate /etc/letsencrypt/live/mcp.yourdomain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/mcp.yourdomain.com/privkey.pem;
client_max_body_size 200m;
location / {
if ($mcp_ok = 0) { return 401; }
proxy_pass http://127.0.0.1:8890;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# Streaming responses must not be buffered
proxy_buffering off;
proxy_cache off;
# Transcription of long videos can take several minutes
proxy_read_timeout 900s;
proxy_send_timeout 900s;
}
}Add the $connection_upgrade map in the http {} block:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}Caddy Configuration
mcp.yourdomain.com {
reverse_proxy 127.0.0.1:8890 {
flush_interval -1
header_up X-Forwarded-Proto {scheme}
header_up X-Forwarded-Host {host}
transport http {
read_timeout 900s
}
}
}Firewall
sudo ufw allow 80,443/tcp
sudo ufw deny 8890Production Deployment
Option A: Docker Compose (Recommended)
The provided Dockerfile bundles Python 3.12, ffmpeg, and tesseract-ocr with Russian and English dictionaries.
git clone https://github.com/bledny1099/sSmcp.git /opt/sSmcp
cd /opt/sSmcp
cp .env.example .env
# Set SSMCP_BEARER_TOKEN=$(openssl rand -hex 24) in .envStart the container:
docker compose up -d --buildThe named Docker volume ssmcp_data persists downloaded Whisper weights and quota state across container rebuilds.
Option B: Bare-Metal systemd Service
Create /etc/systemd/system/ssmcp.service:
[Unit]
Description=sSmcp (socialSimple MCP) Server
After=network-online.target
Wants=network-online.target
[Service]
User=ssmcp
WorkingDirectory=/opt/sSmcp
EnvironmentFile=/opt/sSmcp/.env
ExecStart=/opt/sSmcp/.venv/bin/ssmcp
Restart=always
RestartSec=5
StartLimitIntervalSec=0
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/data /var/www/uploads
MemoryMax=4G
OOMPolicy=continue
[Install]
WantedBy=multi-user.targetEnable and start the service:
sudo systemctl daemon-reload
sudo systemctl enable --now ssmcp.service
sudo systemctl status ssmcp.serviceKeeping yt-dlp current
Social platforms change page structures frequently. Schedule a weekly update on your server:
/opt/sSmcp/.venv/bin/pip install -U yt-dlp && systemctl restart ssmcp.serviceVerifying the deployment
# 1. Healthcheck endpoint
curl -s http://127.0.0.1:8890/health
# 2. Verify token protection over HTTPS
curl -s -o /dev/null -w '%{http_code}\n' https://mcp.yourdomain.com/mcp
# 3. Test MCP initialize handshake
curl -sN https://mcp.yourdomain.com/mcp \
-H 'Authorization: Bearer YOUR_SSMCP_BEARER_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'Client Configuration
1. Cursor, Antigravity IDE, Windsurf
Option 1: Local stdio (mcp_config.json or .cursor/mcp.json)
{
"mcpServers": {
"sSmcp": {
"command": "/ABSOLUTE/PATH/TO/sSmcp/.venv/bin/ssmcp",
"env": {
"SSMCP_TRANSPORT": "stdio",
"SSMCP_WHISPER_MODEL": "small",
"SSMCP_OCR_ENABLED": "true",
"SSMCP_OCR_LANGUAGES": "rus+eng"
}
}
}
}Option 2: Remote Streamable HTTP
{
"mcpServers": {
"sSmcp": {
"url": "https://mcp.yourdomain.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_SSMCP_BEARER_TOKEN"
}
}
}
}2. Claude Desktop
Configure claude_desktop_config.json:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"sSmcp": {
"command": "/ABSOLUTE/PATH/TO/sSmcp/.venv/bin/ssmcp",
"env": {
"SSMCP_TRANSPORT": "stdio",
"SSMCP_WHISPER_MODEL": "small",
"SSMCP_OCR_LANGUAGES": "rus+eng"
}
}
}
}3. Claude Mobile (iOS / Android) & Claude Web
Open Claude and go to Settings -> Connectors.
Click Add custom connector.
Fill in:
Name:
sSmcpURL:
https://mcp.yourdomain.com/mcpAuthentication: If using Bearer token, select No sign-in and click + Add header:
Key:
AuthorizationValue:
Bearer <YOUR_SSMCP_BEARER_TOKEN>
Alternatively, if using OAuth 2.1, select OAuth and log in with your configured password or Google account.
Click Add connector. All 20 tools become available in your chats.
4. Claude Code CLI
claude mcp add sSmcp -- /ABSOLUTE/PATH/TO/sSmcp/.venv/bin/ssmcpUsage Examples
User: "Summarize this TikTok and give me the text shown on screen: https://vt.tiktok.com/ZSqa7P1oy/"The assistant calls tiktok_get_transcript(url="...", include_ocr=True). sSmcp transcribes the spoken speech with Faster-Whisper, extracts keyframes, and runs Tesseract OCR on any text slides or code snippets.
User: "Find the top 3 most popular recent YouTube videos on 'quantum computing' and get the full transcript of the first one."The assistant calls youtube_search(query="quantum computing", order="viewCount", max_results=3), followed by youtube_get_transcript(url="...") to retrieve the video transcript with timestamps.
User: "Read this Instagram carousel and tell me what is written across all slides: https://www.instagram.com/p/DB123456789/"The assistant calls instagram_get_transcript(url="..."). sSmcp downloads the carousel slides and runs OCR across every frame.
Troubleshooting
Symptom | Cause and fix |
| Platform anti-bot challenge triggered. Ensure |
| Install |
Process killed during transcription | System ran out of memory. Switch to a smaller model ( |
Empty audio transcript on a video with music | The video has no human speech. If the video contains text slides, check the |
Quota exceeded error on YouTube search | YouTube Data API v3 daily quota reached. Check usage with |
| The service account cannot write to |
Client disconnects during long transcriptions | Increase |
License
This server cannot be deployed
Maintenance
Related MCP Connectors
Transcribe, read and download public Reels, TikToks and YouTube videos, plus sourced creator data
X (Twitter) search, profiles and trends, YouTube search, video stats and comments, TikTok comments.
Fetch transcripts, subtitles, chapters, metadata and frames from YouTube and 10+ video platforms
Your AI's eyes and ears on social media: read any TikTok, Instagram, YouTube or X post by link
Related MCP Servers
AlicenseNot gradedqualityDmaintenanceEnables AI agents to fetch and digest content from 30+ platforms (Twitter, YouTube, Reddit, etc.) via a unified API. Supports multi-format output, transcription, and direct Obsidian sync.19BSD 2-Clause "Simplified"- AlicenseNot gradedqualityDmaintenanceTransforms social media links (TikTok, Instagram, YouTube) and videos into text context with transcription, OCR, and metadata for AI agents like Claude and Cursor.MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP-compatible assistants to retrieve caption text from YouTube videos as either plain text or timestamped snippets for reading, summarizing, or searching. Supports local stdio and stateless HTTP deployments for integration with Claude Desktop, Claude Code, Cursor, and similar clients.MIT
- AlicenseAqualityBmaintenanceExposes public YouTube data — transcripts with timestamps and language listings, keyword search, video metadata and statistics, comments, channels, channel uploads, and categories — as read-only tools an LLM can call over stdio. It runs as a single local process using only a YouTube Data API key, with SQLite caching, quota tracking, and no OAuth or account access.11MIT