# GitTube MCP

MCP server for downloading videos and audio from 1000+ sites. Works with Claude, Cursor, opencode, and more.

## Quick Start

Tell your LLM:
```
Install GitTube from https://gairxx.github.io/gittube-mcp/
```

Or install manually:
```bash
curl -fsSL https://raw.githubusercontent.com/gairxx/gittube-mcp/main/install.sh | bash
```

## Features

- **Search YouTube** — find videos by query, no URL needed
- **Playlist Support** — list and download entire YouTube playlists
- **1000+ Sites** — YouTube, Vimeo, Twitter/X, TikTok, Instagram, and more
- **Video or Audio** — download MP4/WebM at up to 2160p, or extract audio to MP3
- **Works Everywhere** — Claude Desktop, Claude Code, Cursor, opencode, Continue.dev

## MCP Tools

The server exposes 6 tools to your AI agent:

| Tool | Description |
|------|-------------|
| `search` | Search YouTube for videos by query |
| `list_playlist` | List all videos in a playlist |
| `download_playlist` | Download all videos in a playlist |
| `video_info` | Fetch metadata for a video URL |
| `download_video` | Download a video (quality: best/2160p/1080p/720p/480p) |
| `download_audio` | Extract audio as MP3 (quality: 320k/192k/128k) |

## Agent Configuration

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gittube": {
      "command": "node",
      "args": ["~/.gittube/mcp/server.mjs"]
    }
  }
}
```

### Claude Code

Add to `~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "gittube": {
      "command": "node",
      "args": ["~/.gittube/mcp/server.mjs"]
    }
  }
}
```

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "gittube": {
      "command": "node",
      "args": ["~/.gittube/mcp/server.mjs"]
    }
  }
}
```

### opencode

Add to `~/.config/opencode/opencode.json`:

```json
{
  "mcp": {
    "gittube": {
      "type": "local",
      "command": ["node", "~/.gittube/mcp/server.mjs"],
      "enabled": true
    }
  }
}
```

### Continue.dev

Add to `~/.continue/mcpServers.json`:

```json
{
  "mcpServers": {
    "gittube": {
      "command": "node",
      "args": ["~/.gittube/mcp/server.mjs"]
    }
  }
}
```

## CLI Usage

The installer also sets up a CLI tool for direct terminal use:

```bash
# Search YouTube
gittube --search "lofi hip hop beats"

# Download video
gittube -v https://youtu.be/abc123
gittube -v 1080p https://youtu.be/abc123 ~/Movies

# Extract audio
gittube -a https://youtu.be/abc123 ~/Music/song.mp3

# Download playlist
gittube --playlist -v 1080p https://youtube.com/playlist?list=PLxxx ~/Videos

# List playlist contents
gittube --list-playlist https://youtube.com/playlist?list=PLxxx
```

## Manual Installation

### From npm

```bash
npm install -g gittube-mcp
```

### From source

```bash
git clone https://github.com/gairxx/gittube-mcp.git
cd gittube-mcp
npm install
```

## How it works

GitTube MCP uses [yt-dlp](https://github.com/yt-dlp/yt-dlp) under the hood, which automatically downloads a standalone binary on first use. No manual yt-dlp installation required.

The MCP server communicates over stdio, making it compatible with any MCP client.

## License

MIT