social-video-mcp

MCP server that gives AI agents the ability to play videos from YouTube and TikTok, browse your accounts, and control playback — all through a lightweight mpv player window.

Built for Claude Code and any MCP-compatible client.

https://github.com/user-attachments/assets/08ddb1b3-ed0f-4de3-b465-c0b58ebfa894

Features

Playback — Play videos from YouTube or TikTok in a native mpv window with full remote control:

Play, pause, stop, seek
Playlist playback with next/prev navigation and shuffle
Queue videos without interrupting current playback
Audio-only mode for podcasts and music while you code
Authenticated playback via browser cookies (age-restricted, private videos)

Smart Recommendations — Ask for similar content based on what's currently playing. Finds related videos and queues them automatically.

Infinite Playlists — TikTok and YouTube Shorts playlists auto-refill as you watch. Never runs out.

YouTube Account — Browse your YouTube account directly from your AI agent:

Subscription feed, liked videos, watch later, history
List subscribed channels
Browse channel uploads and Shorts
Search YouTube with personalized results

TikTok — Browse and play TikTok content:

Fetch videos from any TikTok user profile
Play a user's videos as a continuous playlist

Multi-Browser Support — Switch between Chrome, Firefox, Brave, Edge, Safari, Opera, Chromium, or Vivaldi for cookie-based authentication.

Video Info — Fetch metadata without playing: title, description, chapters, duration, tags, view/like counts.

Prerequisites

brew install mpv yt-dlp

mpv — Lightweight video player
yt-dlp — Video stream resolver and cookie extractor
A supported browser — Logged into YouTube/TikTok (Chrome, Firefox, Brave, Edge, Safari, Opera, Chromium, Vivaldi)
Node.js >= 18

Installation

git clone https://github.com/ronantakizawa/social-video-mcp.git
cd social-video-mcp
npm install
npm run build

Configuration

Add to your Claude Code config (~/.claude.json):

{
  "mcpServers": {
    "social-video": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/social-video-mcp/dist/index.js"]
    }
  }
}

Then restart Claude Code.

Tools

Playback

Tool	Description
`play_video`	Play a YouTube or TikTok video. Optional `timestamp` and `audio_only` mode.
`play_audio`	Play audio only — no video window. Great for podcasts and music.
`play_playlist`	Play an entire YouTube playlist. Optional `shuffle`.
`queue_video`	Add a video to the queue without interrupting current playback.
`pause_video`	Toggle pause/resume.
`stop_video`	Stop playback and close the player window.
`seek_video`	Seek to an absolute position in seconds.
`next_video`	Skip to the next video in a playlist.
`prev_video`	Go back to the previous video in a playlist.
`get_status`	Get current playback state: title, position, duration, paused.

Smart Features

Tool	Description
`play_similar`	Find and play/queue videos similar to what's currently playing.

YouTube Account

Tool	Description
`get_youtube_feed`	Fetch your subscription feed, liked videos, watch later, or history.
`get_subscribed_channels`	List your subscribed YouTube channels.
`get_channel_videos`	List recent uploads from a specific channel.
`get_channel_shorts`	List recent Shorts from a specific channel.
`get_subscription_shorts`	Fetch recent Shorts from your subscribed channels.
`play_shorts`	Play Shorts as a continuous auto-advancing playlist.
`search_youtube`	Search YouTube with personalized results.

TikTok

Tool	Description
`get_tiktok_user_videos`	Fetch recent videos from a TikTok user profile.
`play_tiktok_user`	Play a TikTok user's videos as an infinite continuous playlist.

Settings

Tool	Description
`set_browser`	Switch browser for cookie auth (chrome, firefox, brave, edge, safari, opera, chromium, vivaldi).
`get_browser`	Check which browser is currently active.
`get_video_info`	Fetch full video metadata from YouTube or TikTok.

How It Works

Playback: Spawns mpv with --input-ipc-server for JSON IPC control over a Unix socket. All playback commands (pause, seek, next/prev) are sent through this socket.
Data Fetching: Calls yt-dlp directly with -J --flat-playlist --cookies-from-browser <browser> to fetch structured JSON from video platforms.
Authentication: Reads cookies from your browser's local storage via yt-dlp's --cookies-from-browser flag. No OAuth setup required — if you're logged into a platform in your browser, it just works.
Auto-Refill: A background monitor watches playlist position and fetches more content when running low, appending via mpv's loadfile append IPC command.

Platform Support

Feature	YouTube	TikTok
Play single video	Yes	Yes
User profile feed	Yes	Yes
Account feeds	Yes (subs, liked, history)	No
Search	Yes	No
Shorts	Yes	N/A
Queue management	Yes	Yes
Audio-only	Yes	Yes
Smart recommendations	Yes	Yes

Example Usage

> Play my subscription feed
> Search YouTube for "rust programming tutorials" and play the first result
> Show me the latest TikToks from @nba
> Play TikTok videos from @khaby.lame
> Queue this video without stopping what's playing: <url>
> Play similar videos to what's on now
> Just play the audio, I don't need video
> Switch to Firefox for cookies
> What chapters does this video have? Then skip to chapter 3

License

MIT

social-video-mcp

social-video-mcp

Features

Prerequisites

Installation

Configuration

Tools

Playback

Smart Features

YouTube Account

TikTok

Settings

How It Works

Platform Support

Example Usage

License

Reviews