yutu

yutu is a fully functional MCP server and CLI for YouTube to automate your YouTube workflows. It can manipulate almost all YouTube resources, like videos, playlists, channels, comments, captions, and more. 中文文档

Table of Contents

• Prerequisites
• Installation
  • GitHub Actions
  • Docker
  • Gopher
  • Linux
  • macOS
  • Windows
  • Verifying Installation
• MCP Server
• Usage
• Features
• Contributing

Prerequisites

Before you begin, an account on Google Cloud Platform is required to create a Project and enable these APIs for this project, in APIs & Services -> Enable APIs and services -> + ENABLE APIS AND SERVICES:

• YouTube Data API v3(Required)
• YouTube Analytics API(Optional)
• YouTube Reporting API(Optional)

After enabling the APIs, create an OAuth content screen with yourself as test user, then create an OAuth Client ID of type Web Application with http://localhost:8216 as the redirect URI.

Download this credential to your local machine with name client_secret.json, it should look like

{
  "web": {
    "client_id": "11181119.apps.googleusercontent.com",
    "project_id": "yutu-11181119",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
    "client_secret": "XXXXXXXXXXXXXXXX",
    "redirect_uris": [
      "http://localhost:8216"
    ]
  }
}

To verify this credential, run the following command

❯ yutu auth --credential client_secret.json

A browser window will open asking for your permission to access your YouTube account, after granting the permission, a token will be generated and saved to youtube.token.json.

{
  "access_token": "ya29.XXXXXXXXX",
  "token_type":"Bearer",
  "refresh_token":"1//XXXXXXXXXX",
  "expiry":"2024-05-26T18:49:56.1911165+08:00"
}

By default, yutu will read client_secret.json and youtube.token.json from the current directory, --credential/-c and --cacheToken/-t flags are available only in auth subcommand. To modify the default path in all subcommands, set these environment variables

❯ export YUTU_CREDENTIAL=client_secret.json
❯ export YUTU_CACHE_TOKEN=youtube.token.json
# or
❯ YUTU_CREDENTIAL=client_secret.json YUTU_CACHE_TOKEN=youtube.token.json yutu subcommand --flag value

Installation

You can download yutu from releases page directly, or use the following methods as you prefer.

GitHub Actions

There are two actions available for yutu, one is for general purpose and the other is for uploading video to YouTube. Refer to youtube-action and youtube-uploader for more information.

Docker

❯ docker pull ghcr.io/eat-pray-ai/yutu:latest
❯ docker run --rm ghcr.io/eat-pray-ai/yutu:latest
# make sure client_secret.json is in the current directory
❯ docker run --rm -it -u $(id -u):$(id -g) -v $(pwd):/app -p 8216:8216 ghcr.io/eat-pray-ai/yutu:latest

Gopher

❯ go install github.com/eat-pray-ai/yutu@latest

Linux

❯ curl -sSfL https://raw.githubusercontent.com/eat-pray-ai/yutu/main/scripts/install.sh | bash

macOS

Install yutu using Homebrew🍺(recommended), or run the shell script.

❯ brew install yutu

# or
❯ curl -sSfL https://raw.githubusercontent.com/eat-pray-ai/yutu/main/scripts/install.sh | bash

Windows

❯ winget install yutu

Verifying Installation

Verify the integrity and provenance of yutu using its associated cryptographically signed attestations.

# Docker
❯ gh attestation verify oci://ghcr.io/eat-pray-ai/yutu:latest --repo eat-pray-ai/yutu

# Linux and macOS(if installed using shell script)
❯ gh attestation verify $(which yutu) --repo eat-pray-ai/yutu

# Windows
❯ gh attestation verify $(where.exe yutu.exe) --repo eat-pray-ai/yutu

Agent

yutu provides an agent mode to automate YouTube workflows. Currently, the agent mode is in the experimental stage under active development, only supports Google's Gemini models with the following environment variables set:

❯ export YUTU_AGENT_MODEL=gemini-3-pro-preview
❯ export YUTU_LLM_API_KEY=your_gemini_api_key
// Optional settings
❯ export GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com/
❯ export YUTU_AGENT_INSTRUCTION=Your custom instruction here

Then run the following command for detail usage:

❯ yutu agent --help

MCP Server

As a MCP server, yutu can be used in MCP clients like Claude Desktop, VS Code or Cursor, which allows you to interact with YouTube resources in a chat-like interface.

Before using yutu as an MCP server, make sure yutu is installed(see Installation section), and you have a valid client_secret.json and youtube.token.json files(refer to Prerequisites section).

You can add yutu as a MCP server in VS Code or Cursor by clicking corresponding badge above, or add the following configuration manually to your MCP client. Remember to replace the values of YUTU_CREDENTIAL and YUTU_CACHE_TOKEN with correct paths on your local machine.

{
  "yutu": {
    "type": "stdio",
    "command": "yutu",
    "args": [
      "mcp"
    ],
    "env": {
      "YUTU_CREDENTIAL": "/absolute/path/to/client_secret.json",
      "YUTU_CACHE_TOKEN": "/absolute/path/to/youtube.token.json"
    }
  }
}

Usage

❯ yutu        
yutu is a fully functional MCP server and CLI for YouTube, which can manipulate almost all YouTube resources

Usage:
  yutu [flags]
  yutu [command]

Available Commands:
  activity               List YouTube activities
  agent                  Start agent to automate YouTube workflows
  auth                   Authenticate with YouTube API
  caption                Manipulate YouTube captions
  channel                Manipulate YouTube channels
  channelBanner          Insert Youtube channel banner
  channelSection         Manipulate YouTube channel sections
  comment                Manipulate YouTube comments
  commentThread          Manipulate YouTube comment threads
  completion             Generate the autocompletion script for the specified shell
  help                   Help about any command
  i18nLanguage           List YouTube i18n languages
  i18nRegion             List YouTube i18n regions
  mcp                    Start MCP server
  member                 List channel's members' info
  membershipsLevel       List memberships levels' info
  playlist               Manipulate YouTube playlists
  playlistImage          Manipulate YouTube playlist images
  playlistItem           Manipulate YouTube playlist items
  search                 Search for YouTube resources
  subscription           Manipulate YouTube subscriptions
  superChatEvent         List Super Chat events for a channel
  thumbnail              Set thumbnail for a video
  version                Show the version of yutu
  video                  Manipulate YouTube videos
  videoAbuseReportReason List YouTube video abuse report reasons
  videoCategory          List YouTube video categories
  watermark              Manipulate YouTube watermarks

Flags:
  -h, --help   help for yutu

Use "yutu [command] --help" for more information about a command.

Features

Please refer to FEATURES.md for more information.

Contributing

Please refer to CONTRIBUTING.md for more information.

Star History