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

Quick Start (npm)

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

{
  "mcpServers": {
    "social-video": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "social-video-mcp"]
    }
  }
}

Then restart Claude Code. That's it.

From Source

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

Config for local install:

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

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