> ## Documentation Index
> Fetch the complete documentation index at: https://docs.transcribetube.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI & MCP

> Transcribe YouTube videos from the command line, or wire TranscribeTube into Claude, Cursor and other AI clients over the Model Context Protocol (MCP).

The `tube` CLI turns any YouTube URL (or media file) into a transcript — `txt`, `srt`,
`vtt`, `md` or `json` — straight from your terminal. The same package ships an
[MCP](https://modelcontextprotocol.io) server, so AI clients like Claude and Cursor
can transcribe and read YouTube transcripts as a native tool.

<Note>
  You need a TranscribeTube account and an API key. Grab one from your
  [API key page](https://app.transcribetube.com/account/api-key). Transcription
  consumes account credit, same as the web app.
</Note>

## Install

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @transcribetube/cli
  ```

  ```bash pnpm theme={null}
  pnpm add -g @transcribetube/cli
  ```

  ```bash npx (no install) theme={null}
  npx @transcribetube/cli transcribe "https://youtu.be/dQw4w9WgXcQ" --wait
  ```
</CodeGroup>

This installs the `tube` binary.

## Authenticate

Store your API key once:

```bash theme={null}
tube login
# opens app.transcribetube.com/account/api-key, then paste your key
```

For CI or headless environments, pass it non-interactively or via the
`TUBE_API_KEY` environment variable:

<CodeGroup>
  ```bash flag theme={null}
  tube login --api-key "tt_live_xxx"
  ```

  ```bash env var theme={null}
  export TUBE_API_KEY="tt_live_xxx"
  tube whoami
  ```
</CodeGroup>

Verify with `tube whoami` (prints the account email and remaining credit).

## Transcribe a YouTube video

The one-liner most people come for:

```bash theme={null}
tube transcribe "https://youtu.be/dQw4w9WgXcQ" --wait
```

`--wait` blocks until processing finishes and prints the transcript. Without it,
the command queues the job and returns the project id so you can poll later.

### Choose an output format

`txt` (default), `srt`, `vtt`, `md`, and `json` are supported via `-f/--format`:

<CodeGroup>
  ```bash SRT subtitles theme={null}
  tube transcribe "https://youtu.be/dQw4w9WgXcQ" --wait -f srt > captions.srt
  ```

  ```bash WebVTT theme={null}
  tube transcribe "https://youtu.be/dQw4w9WgXcQ" --wait -f vtt > captions.vtt
  ```

  ```bash Markdown theme={null}
  tube transcribe "https://youtu.be/dQw4w9WgXcQ" --wait -f md > transcript.md
  ```

  ```bash JSON (words + timecodes) theme={null}
  tube transcribe "https://youtu.be/dQw4w9WgXcQ" --wait -f json > transcript.json
  ```
</CodeGroup>

### Common flags

| Flag                 | Description                                               |
| -------------------- | --------------------------------------------------------- |
| `-w, --wait`         | Wait for completion and print the transcript              |
| `-f, --format <fmt>` | `txt` \| `srt` \| `vtt` \| `md` \| `json` (default `txt`) |
| `-l, --lang <code>`  | Language hint, e.g. `en`. Omit to auto-detect             |
| `--webhook <url>`    | POST to this URL when transcription completes             |
| `--json`             | Machine-readable JSON output for any command              |

## Work with projects

Every transcription is a project. Fetch transcripts later, in any format:

```bash theme={null}
tube project list                       # recent projects + status
tube project get <id>                   # project details
tube project watch <id>                 # poll until DONE or ERROR
tube project transcript <id> -f srt     # fetch a finished transcript
```

`project transcript` also takes `--no-speakers` and `--no-timecodes` to strip
speaker labels or timecodes from the output.

## MCP server (Claude, Cursor, Claude Code)

The package ships an MCP server over stdio. Point any MCP-capable client at
`tube mcp` and it gains three tools:

| Tool                 | What it does                                                        |
| -------------------- | ------------------------------------------------------------------- |
| `transcribe_youtube` | Transcribe a YouTube URL and return speaker-labeled, timecoded text |
| `get_transcript`     | Fetch an existing project's transcript by id, in any format         |
| `list_projects`      | List recent projects with their ids and status                      |

### Claude Desktop / Claude Code

Add this to your MCP config (`claude_desktop_config.json`, or `.mcp.json` for
Claude Code). The server reads your key from `TUBE_API_KEY`:

```json theme={null}
{
  "mcpServers": {
    "transcribetube": {
      "command": "tube",
      "args": ["mcp"],
      "env": { "TUBE_API_KEY": "tt_live_xxx" }
    }
  }
}
```

Then just ask: *"Transcribe this YouTube video and summarize the key points: \<url>."*
Claude calls `transcribe_youtube`, gets the text, and works with it directly — no
copy-paste.

### Cursor

Add the same block under `mcpServers` in Cursor's MCP settings. The tools appear
automatically in the agent's tool list.

<Note>
  The MCP server transcribes synchronously and waits up to 10 minutes for long
  videos. For batch or unattended jobs, prefer the CLI with `--webhook`.
</Note>

## Scripting examples

<CodeGroup>
  ```bash Caption a whole channel (bash) theme={null}
  # transcript.txt for every URL in urls.txt
  while read url; do
    id=$(tube transcribe "$url" --json | jq -r '.id')
    echo "queued $id for $url"
  done < urls.txt
  ```

  ```bash Pipe into an LLM theme={null}
  tube transcribe "https://youtu.be/dQw4w9WgXcQ" --wait -f md \
    | your-llm "Summarize this transcript into 5 bullet points"
  ```
</CodeGroup>

## API early access

<Tip>
  **🔌 Need transcription as a hosted API for your agents?** TranscribeTube is opening an
  MCP-native transcription API. **[Request early access →](https://app.transcribetube.com/api-waitlist?from=docs)**
</Tip>

## Reference

* Full REST API: [API Documentation](/api-documentation/introduction)
* Authentication & keys: [Authentication](/api-documentation/authentication)
* Project lifecycle (UPLOAD → TRANSCRIPTION → DONE): [Lifecycle](/api-documentation/lifecycle)