# watch-cli

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 260 repo stars
- Author: sonpiaz
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/sonpiaz/watch-cli/tree/HEAD/mcp-server
- Updated: 2026-09-13
- Security check: automated, 2026-11-16 (text) — warning: a command downloads a script from raw.githubusercontent.com and runs it right away. Do not run such commands without an explicit yes from the human.
- HTML: https://affpapa.org/en/nevibecode/mcp/watch-cli

## What it 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`.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `KYMA_API_KEY`, `GROQ_API_KEY`, `WATCH_AUDIO_MODE` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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

### Codex

**Platform CLI**
```bash
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-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
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-mcp
```
Replace <…> with your own values

## When to use it
- 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
- 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

## Similar
- [Yueying – Let AI watch videos](https://affpapa.org/en/nevibecode/mcp/yueying-let-ai-watch-videos.md) — MCP server · ★ 13 repo stars
- [watch-video](https://affpapa.org/en/nevibecode/plugins/codepawl-watch-video.md) — plugin · ★ 350 repo stars
- [Video Extract](https://affpapa.org/en/nevibecode/mcp/video-extract.md) — MCP server · ★ 12 repo stars
- [youtube](https://affpapa.org/en/nevibecode/commands/youtube.md) — command · ★ 5412 repo stars
- [youtube-transcript](https://affpapa.org/en/nevibecode/skills/tubeagentkit-youtube-transcript.md) — skill · ★ 41 repo stars
- [youtube-skills](https://affpapa.org/en/nevibecode/plugins/youtube-skills.md) — plugin · ★ 1596 repo stars

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
