Skip to main content
MCP server CX Codex

watch-cli — Claude Code MCP server: what it does, how to install

watch-cli gives your agent a social video as frames plus a transcript. Useful when a YouTube, X or TikTok clip has to become a diagram, notebook or step list.

MIT ★ 260 updated 2026-09-13

Install into Claude Code · Platform CLI All methods and platforms ↓
claude mcp add --env KYMA_API_KEY=<KYMA_API_KEY> --env GROQ_API_KEY=<GROQ_API_KEY> --env WATCH_AUDIO_MODE=<WATCH_AUDIO_MODE> --transport stdio mcp-server -- npx -y @sonpiaz/watch-cli-mcp
Open on GitHub

What watch-cli does

The server registers a single tool, watch. You pass it a video link from YouTube, X / Twitter, LinkedIn, TikTok, Vimeo, Reddit or Facebook, plus an optional frame count between 1 and 64 (8 if you leave it out). The reply is the CLI's JSON, unchanged: frames taken at even intervals and the transcript. From that the agent can draft an architecture diagram or a runnable notebook.

The server is a Node.js 18+ stdio process that shells out to the watch command. If watch is not on your PATH, nothing works, because the package does not ship the CLI. Install it first.

Failures carry a tag=... in the message. Auth and region download errors (download-auth, download-region) come back as invalid params, so you can retry with cookies or another link. If only the transcript fails (exit code 4), you still get the frames and transcript is null.

What it helps with

  • break down a YouTube or TikTok clip without watching all of it
  • draft an architecture diagram from a video walkthrough
  • build a runnable notebook from a tutorial posted on X
  • turn a video lesson into a step-by-step cheat sheet
  • pull a chosen number of frames, 1 to 64, from a video

Example prompts for the agent

  • Run watch on this YouTube link and sketch the architecture the video describes
  • Use watch-cli on this X post with 8 frames and build a notebook from it
  • Go through this Vimeo tutorial with watch-cli and write a step-by-step cheat sheet

How to install watch-cli

Platform CLI

claude mcp add --env KYMA_API_KEY=<KYMA_API_KEY> --env GROQ_API_KEY=<GROQ_API_KEY> --env WATCH_AUDIO_MODE=<WATCH_AUDIO_MODE> --transport stdio mcp-server -- npx -y @sonpiaz/watch-cli-mcp

Replace <…> with your own values

Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more

Questions about watch-cli

How do I install watch-cli in Claude Code?

Run claude mcp add watch-cli -e KYMA_API_KEY=<KYMA_API_KEY> -e GROQ_API_KEY=<GROQ_API_KEY> -- npx -y @sonpiaz/watch-cli-mcp. You also need Node.js 18 or newer and the watch CLI on your PATH.

What does watch-cli do?

It gives the agent a watch tool. Send it a social video link and it returns frames and a transcript in one JSON object, which the agent can turn into a diagram, notebook, component or cheat sheet.

What happens when a video has no usable transcript?

The call still succeeds with isError: false. Frames are filled in, transcript is null, and the JSON carries exit_code: 4, which the agent can check to treat the result as partial.

Similar MCP servers

All MCP servers for Agent setup: memory, context, orchestration →

Project sponsors

Companies that keep this analytics open