`yutu`

yutu is a CLI, MCP server, and AI agent for YouTube that automates your entire YouTube workflow — from uploading and optimizing videos to managing comments, playlists, and channel branding — so you can get more views, higher click-through rates, and stronger audience engagement with less manual effort. 中文文档

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:

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

Global Environment Variables

Variable	Description	Default
`YUTU_CREDENTIAL`	Path, base64, or JSON of OAuth client secret	`client_secret.json`
`YUTU_CACHE_TOKEN`	Path, base64, or JSON of cached OAuth token	`youtube.token.json`
`YUTU_ROOT`	Root directory for file resolution	Current working directory
`YUTU_LOG_LEVEL`	Log level: `DEBUG`, `INFO`, `WARN`, `ERROR`	`INFO`

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. The system uses a multi-agent architecture where a central orchestrator delegates tasks to specialized agents:

Agent	Role	Capabilities
Orchestrator	Coordinates the entire workflow, plans strategy, and delegates to sub-agents	YouTube growth strategy, SEO optimization, task routing
Retrieval	Gathers data from YouTube and the web (read-only)	List/search videos, channels, playlists, comments, captions, subscriptions, members, and more; Google Search
Modifier	Creates and updates YouTube content	Upload videos, create playlists, update metadata, post comments, set thumbnails, manage captions and watermarks
Destroyer	Handles destructive operations with extra caution	Delete videos, playlists, comments, captions, subscriptions, channel sections, and watermarks

Currently, the agent mode is under active development, only supports Google's Gemini models with the following environment variables set:

❯ export YUTU_ADVANCED_MODEL=google:gemini-3.1-pro-preview
❯ export YUTU_LITE_MODEL=google:gemini-3-flash-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

YUTU_ADVANCED_MODEL is used by the orchestrator agent, while YUTU_LITE_MODEL is used by all other agents. Both use the provider:modelName format (only google is supported). If only one is set, the other defaults to the same value.

Agent Environment Variables

Variable	Description	Required
`YUTU_ADVANCED_MODEL`	Model for orchestrator agent (format: `provider:modelName`)	At least one of `YUTU_ADVANCED_MODEL` or `YUTU_LITE_MODEL`
`YUTU_LITE_MODEL`	Model for sub-agents (format: `provider:modelName`)	At least one of `YUTU_ADVANCED_MODEL` or `YUTU_LITE_MODEL`
`YUTU_LLM_API_KEY`	API key for the model provider	Yes
`GOOGLE_GEMINI_BASE_URL`	Base URL for Gemini API	No
`YUTU_AGENT_INSTRUCTION`	Custom instruction for orchestrator agent	No
`YUTU_RETRIEVAL_INSTRUCTION`	Custom instruction for retrieval agent	No
`YUTU_MODIFIER_INSTRUCTION`	Custom instruction for modifier agent	No
`YUTU_DESTROYER_INSTRUCTION`	Custom instruction for destroyer agent	No

Then run the following command for detail usage:

❯ yutu agent --help
❯ yutu agent --args "help"
# console mode
❯ yutu agent --args "console"
# web mode with three sub-launchers: api, a2a and webui
❯ yutu agent --args "web api a2a webui"

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"
    }
  }
}

Skills

yutu provides a set of skills that extend AI agents with YouTube domain knowledge. Install individual skills to give your agent specialized capabilities for specific YouTube resources.

# Install a single skill (e.g. video management)
❯ npx skills add https://github.com/eat-pray-ai/yutu/tree/main/skills/yutu-video

# Install all skills at once
❯ npx skills add https://github.com/eat-pray-ai/yutu/tree/main/skills

Available Skills

Skill	Description
yutu-activity	Manage activities on YouTube
yutu-caption	Manage YouTube video captions
yutu-channel	Manage YouTube channels
yutu-channelBanner	Manage YouTube channel banners
yutu-channelSection	Manage YouTube channel sections
yutu-comment	Manage YouTube comments
yutu-commentThread	Manage YouTube comment threads
yutu-i18nLanguage	Manage YouTube i18n languages
yutu-i18nRegion	Manage YouTube i18n regions
yutu-member	Manage YouTube channel members
yutu-membershipsLevel	Manage YouTube memberships levels
yutu-playlist	Manage YouTube playlists
yutu-playlistImage	Manage YouTube playlist images
yutu-playlistItem	Manage YouTube playlist items
yutu-search	Manage YouTube search
yutu-subscription	Manage YouTube subscriptions
yutu-superChatEvent	Manage YouTube Super Chat events
yutu-thumbnail	Manage YouTube video thumbnails
yutu-video	Manage YouTube videos
yutu-videoAbuseReportReason	Manage YouTube video abuse report reasons
yutu-videoCategory	Manage YouTube video categories
yutu-watermark	Manage YouTube watermarks

Usage

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

Environment variables:
  YUTU_CREDENTIAL    Path/base64/JSON of OAuth client secret (default: client_secret.json)
  YUTU_CACHE_TOKEN   Path/base64/JSON of cached OAuth token (default: youtube.token.json)
  YUTU_ROOT          Root directory for file resolution (default: current working directory)
  YUTU_LOG_LEVEL     Log level: DEBUG, INFO, WARN, ERROR (default: INFO)

Usage:
  yutu [flags]
  yutu [command]

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

Flags:
  -h, --help   help for yutu

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

Name		Name	Last commit message	Last commit date
Latest commit History 552 Commits
.github		.github
assets		assets
cmd		cmd
docs		docs
internal/tools		internal/tools
pkg		pkg
scripts		scripts
skills		skills
winres		winres
.bazelignore		.bazelignore
.bazelrc		.bazelrc
.bazelversion		.bazelversion
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
AGENTS.md		AGENTS.md
BUILD.bazel		BUILD.bazel
Dockerfile		Dockerfile
LICENSE		LICENSE
MODULE.bazel		MODULE.bazel
MODULE.bazel.lock		MODULE.bazel.lock
README.md		README.md
README_zh.md		README_zh.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go
server.json		server.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

`yutu`

Table of Contents

Prerequisites

Global Environment Variables

Installation

GitHub Actions

Docker

Gopher

Linux

macOS

Windows

Verifying Installation

Agent

Agent Environment Variables

MCP Server

Skills

Usage

Features

Contributing

Star History

About

Uh oh!

Releases 25

Sponsor this project

Uh oh!

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

yutu

Table of Contents

Prerequisites

Global Environment Variables

Installation

GitHub Actions

Docker

Gopher

Linux

macOS

Windows

Verifying Installation

Agent

Agent Environment Variables

MCP Server

Skills

Usage

Features

Contributing

Star History

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 25

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`yutu`

Packages