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
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-mcpWhat 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
watchon 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-mcpReplace <…> with your own values
Platform CLI
codex mcp add mcp-server --env KYMA_API_KEY=<KYMA_API_KEY> --env GROQ_API_KEY=<GROQ_API_KEY> --env WATCH_AUDIO_MODE=<WATCH_AUDIO_MODE> -- npx -y @sonpiaz/watch-cli-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@sonpiaz/watch-cli-mcp"
],
"env": {
"KYMA_API_KEY": "<KYMA_API_KEY>",
"GROQ_API_KEY": "<GROQ_API_KEY>",
"WATCH_AUDIO_MODE": "<WATCH_AUDIO_MODE>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@sonpiaz/watch-cli-mcp"
],
"env": {
"KYMA_API_KEY": "<KYMA_API_KEY>",
"GROQ_API_KEY": "<GROQ_API_KEY>",
"WATCH_AUDIO_MODE": "<WATCH_AUDIO_MODE>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e KYMA_API_KEY=<KYMA_API_KEY> -e GROQ_API_KEY=<GROQ_API_KEY> -e WATCH_AUDIO_MODE=<WATCH_AUDIO_MODE> mcp-server npx -y @sonpiaz/watch-cli-mcpReplace <…> 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.