# watch-cli MCP server

> Allows AI agents to process social videos by extracting frames and transcripts for automated analysis and documentation.

- Repository: https://github.com/sonpiaz/watch-cli
- Page: https://hostedmcp.org/servers/sonpiaz/watch-cli
- Transport: stdio
- Stars: 260
- License: MIT
- Latest version: 0.3.1

## Install

### Claude Code

```sh
claude mcp add --env 'GROQ_API_KEY=<YOUR_GROQ_API_KEY>' --env 'KYMA_API_KEY=<YOUR_KYMA_API_KEY>' watch-cli -- npx -y @sonpiaz/watch-cli-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "watch-cli": {
      "command": "npx",
      "args": [
        "-y",
        "@sonpiaz/watch-cli-mcp"
      ],
      "env": {
        "GROQ_API_KEY": "<YOUR_GROQ_API_KEY>",
        "KYMA_API_KEY": "<YOUR_KYMA_API_KEY>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "watch-cli": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@sonpiaz/watch-cli-mcp"
      ],
      "env": {
        "GROQ_API_KEY": "<YOUR_GROQ_API_KEY>",
        "KYMA_API_KEY": "<YOUR_KYMA_API_KEY>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"watch-cli","type":"stdio","command":"npx","args":["-y","@sonpiaz/watch-cli-mcp"],"env":{"GROQ_API_KEY":"<YOUR_GROQ_API_KEY>","KYMA_API_KEY":"<YOUR_KYMA_API_KEY>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "watch-cli": {
      "command": "npx",
      "args": [
        "-y",
        "@sonpiaz/watch-cli-mcp"
      ],
      "env": {
        "GROQ_API_KEY": "<YOUR_GROQ_API_KEY>",
        "KYMA_API_KEY": "<YOUR_KYMA_API_KEY>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add watch-cli --env 'GROQ_API_KEY=<YOUR_GROQ_API_KEY>' --env 'KYMA_API_KEY=<YOUR_KYMA_API_KEY>' -- npx -y @sonpiaz/watch-cli-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.watch-cli]
command = "npx"
args = ["-y", "@sonpiaz/watch-cli-mcp"]

[mcp_servers.watch-cli.env]
GROQ_API_KEY = "<YOUR_GROQ_API_KEY>"
KYMA_API_KEY = "<YOUR_KYMA_API_KEY>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'GROQ_API_KEY=<YOUR_GROQ_API_KEY>' -e 'KYMA_API_KEY=<YOUR_KYMA_API_KEY>' watch-cli npx -- -y @sonpiaz/watch-cli-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "watch-cli": {
      "command": "npx",
      "args": [
        "-y",
        "@sonpiaz/watch-cli-mcp"
      ],
      "env": {
        "GROQ_API_KEY": "<YOUR_GROQ_API_KEY>",
        "KYMA_API_KEY": "<YOUR_KYMA_API_KEY>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `GROQ_API_KEY` | no | yes | Groq API key for direct BYOK transcription (alternative to Kyma). Set this instead of KYMA_API_KEY if you prefer direct provider. |
| `KYMA_API_KEY` | no | yes | Kyma API key (default backend). Get one at https://kymaapi.com — first $0.50 free, then pay-per-use (~$0.05 per 1-hour video). Optional if WATCH_AUDIO_MODE=local (whisper.cpp) or GROQ_API_KEY is set instead. |
| `WATCH_AUDIO_MODE` | no | no | Backend routing override. Values: kyma (default), byok (use GROQ_API_KEY), local (whisper.cpp on $PATH, fully offline). |

## FAQ

### What social media platforms are supported?

The tool supports YouTube, X / Twitter, LinkedIn, TikTok, Vimeo, Reddit, and Facebook.

### Do I need to install the watch CLI separately?

Yes, the MCP server shells out to the watch CLI and does not bundle it, so you must have it installed on your PATH.