Watch Cli

io.github.sonpiazPublished by GitHub account sonpiazv0.3.1Updated Oct 28, 2026

Hand any social video to your AI agent — frames + transcript bundled. MCP server for watch-cli.

VerifiedSTDIODesktop onlyMedia & DesignAI & ML

Overview

AI-generated overview

Wraps the watch CLI as one MCP tool so an assistant can pull evenly spaced frames plus a transcript from a social video URL.

What you can do
  • Fetch a social video by URL and return extracted frames with a transcript as one JSON object
  • Choose how many evenly spaced frames to extract, from 1 to 64, defaulting to 8
  • Work with links from YouTube, X/Twitter, LinkedIn, TikTok, Vimeo, Reddit and Facebook
  • Receive tagged error messages for missing dependencies, download auth or region blocks, network failures and usage errors
  • Detect partial results where frames are returned but the transcript is null
When to use it
Useful when you want an assistant to look at and summarize a social video, or turn it into a diagram, cheat sheet or notes, without manually downloading it. It fits agents that already have the watch CLI installed and a transcription backend available.
Requirements
Node.js 18 or newer, plus the watch CLI installed and on PATH (the server shells out to it and does not bundle it). A transcription backend: KYMA_API_KEY by default, or GROQ_API_KEY with WATCH_AUDIO_MODE=byok, or WATCH_AUDIO_MODE=local with whisper.cpp on PATH for offline use. Network access to the video source.
Before you install
Requires a third-party API key: KYMA_API_KEY is billed pay-per-use after a small free credit, and GROQ_API_KEY is sent to Groq. The README's install step pipes a remote shell script into bash, so review it before running. Video URLs are sent to the transcription backend and the video host, and some sources may need cookies to bypass auth or region blocks.

Installation

In SourceWeft

  1. Open Watch Cli in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@sonpiaz/watch-cli-mcp

MCP (Model Context Protocol) stdio server that exposes watch-cli as a callable tool.

Watch any social video → get an architecture diagram, working component, runnable notebook, or step-by-step cheat sheet — automatically.

A single MCP server reaches every MCP-capable agent runtime — Claude Desktop, Claude Code, Cursor, OpenClaw, hermes-agent, Cline, Continue.dev, Windsurf, Zed, Codex, Kiro, VS Code Copilot — without per-IDE plugin work. This package wraps watch-cli so any of them can call it through one channel.

Prerequisites

  • Node.js >= 18.

  • The watch CLI installed and on PATH. Install with:

    bash
    curl -fsSL https://raw.githubusercontent.com/sonpiaz/watch-cli/main/install.sh | bash

The MCP server shells out to watch; it does not bundle the CLI.

Install

bash
npm install -g @sonpiaz/watch-cli-mcp

Or run on demand via npx:

bash
npx -y @sonpiaz/watch-cli-mcp

The binary is watch-cli-mcp. It reads JSON-RPC on stdin, writes JSON-RPC on stdout, and logs to stderr.

Tool

One tool is registered: watch.

Input schema:

json
{  "type": "object",  "properties": {    "url": {      "type": "string",      "format": "uri",      "description": "A social video URL. Supported: YouTube, X / Twitter, LinkedIn, TikTok, Vimeo, Reddit, Facebook."    },    "frames": {      "type": "integer",      "minimum": 1,      "maximum": 64,      "description": "Number of evenly-spaced frames to extract. Default 8."    }  },  "required": ["url"],  "additionalProperties": false}

Output: the v1 JSON object from docs/output-schema.md, passed through verbatim. Read the schema for the field reference.

Error mapping

CLI exitMCP response
0Tool result with the v1 JSON as content[0].text.
2InternalError, message includes tag=missing-dep:<bin>.
3 download-auth / download-regionInvalidParams, message includes the tag — caller can recover with cookies or a different URL.
3 download-network / download-otherInternalError, message includes the tag.
4 (partial success)Tool result with isError: false. Frames populated, transcript null, exit_code: 4 in the JSON payload. Caller branches on obj.exit_code === 4.
64InvalidParams, message includes tag=usage-error.
1 / otherInternalError, message includes the CLI stderr tail (≤ 1 KB).

Tags always ride in the MCP error message field so callers can grep for the same tag=... token they would see in CLI stderr.

Client configuration

Claude Desktop

Config path:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Merge into the existing mcpServers object:

json
{  "mcpServers": {    "watch-cli": {      "command": "npx",      "args": ["-y", "@sonpiaz/watch-cli-mcp"]    }  }}

Restart Claude Desktop after editing.

Cursor

Config path: .cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (user-global). Same mcpServers object shape as Claude Desktop:

json
{  "mcpServers": {    "watch-cli": {      "command": "npx",      "args": ["-y", "@sonpiaz/watch-cli-mcp"]    }  }}

hermes-agent

Config path: optional-skills/mcp.json inside the hermes-agent install, or ~/.hermes-agent/mcp.json user-global. Same mcpServers shape as above.

Other MCP clients

Any MCP-capable agent that accepts an npx command will work with the snippet above. Substitute the client's config path; the command / args pair is portable.

Build from source

bash
git clone https://github.com/sonpiaz/watch-clicd watch-cli/mcp-servernpm installnpm run buildnode dist/index.js

License

MIT. © 2026 Son Piaz.

Source: mcp-server/README.md at commit 06beafb

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.3.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts