# `yutu`
[](https://gitmoji.dev)
[](https://github.com/eat-pray-ai/yutu?tab=Apache-2.0-1-ov-file)
[](https://pkg.go.dev/github.com/eat-pray-ai/yutu)
[](https://raw.githack.com/wiki/eat-pray-ai/yutu/coverage.html)
[](https://github.com/eat-pray-ai/yutu/stargazers)
[](https://github.com/eat-pray-ai/yutu/releases/latest)
[](https://github.com/eat-pray-ai/yutu/actions/workflows/publish.yml)
[](https://github.com/eat-pray-ai/yutu/actions/workflows/codeql.yml)
[](https://github.com/eat-pray-ai/yutu/actions/workflows/test.yml)
[](https://linux.do/tag/2234-tag/2234)
[](https://github.com/eat-pray-ai/yutu/releases/latest)
[](https://formulae.brew.sh/formula/yutu)
[](https://winstall.app/apps/eat-pray-ai.yutu)
[](https://www.npmjs.com/package/@eat-pray-ai/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. [中文文档](./README_zh.md)
[](https://asciinema.org/a/wXIHU4ciFBAKrHfaFNkMoIs12)
## Table of Contents
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Agent](#agent)
- [MCP Server](#mcp-server)
- [Skills](#skills)
- [Usage](#usage)
- [Features](#features)
- [Contributing](#contributing)
## Prerequisites
An account on [Google Cloud Platform](https://console.cloud.google.com/) is required. Set up the following:
1. **Create a GCP Project** and enable these APIs under `APIs & Services -> Enable APIs and services`:
- [YouTube Data API v3](https://console.cloud.google.com/apis/api/youtube.googleapis.com/overview) (Required)
- [YouTube Analytics API](https://console.cloud.google.com/apis/api/youtubeanalytics.googleapis.com/overview) (Optional)
- [YouTube Reporting API](https://console.cloud.google.com/apis/api/youtubereporting.googleapis.com/overview) (Optional)
2. **Create OAuth credentials**:
- Go to `APIs & Services -> OAuth consent screen`, create a consent screen with yourself as a test user
- Go to `Credentials -> Create Credentials -> OAuth Client ID`, select `Desktop app`
- Download the credential file and save it as `client_secret.json`, it should look like
```json
{
"installed": {
"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"
]
}
}
```
3. **Authenticate**:
```bash
yutu auth --credential client_secret.json
```
A browser window will open for you to grant YouTube access. After granting permission, a token is saved to `youtube.token.json`.
```json
{
"access_token": "ya29.XXXXXXXXX",
"token_type": "Bearer",
"refresh_token": "1//XXXXXXXXXX",
"expiry": "2024-05-26T18:49:56.1911165+08:00",
"expires_in": 3599
}
```
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.
### 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
If you're using an AI agent, copy and paste the following prompt to finish the installation:
```plaintext
Install and configure yutu by following https://raw.githubusercontent.com/eat-pray-ai/yutu/refs/heads/main/internal/tools/skillgen/setup.md
```
You can download `yutu` from [releases page](https://github.com/eat-pray-ai/yutu/releases/latest) 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](https://github.com/eat-pray-ai/youtube-action) and [youtube-uploader](https://github.com/eat-pray-ai/youtube-uploader) for more information.
Node.js
```shell
❯ npm i -g @eat-pray-ai/yutu
```
Docker
```shell
❯ 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
```shell
❯ go install github.com/eat-pray-ai/yutu@latest
```
Linux
```shell
❯ curl -sSfL https://raw.githubusercontent.com/eat-pray-ai/yutu/main/scripts/install.sh | bash
```
macOS
Install `yutu` using [Homebrew🍺](https://brew.sh/)(recommended), or run the shell script.
```shell
❯ brew install yutu
# or
❯ curl -sSfL https://raw.githubusercontent.com/eat-pray-ai/yutu/main/scripts/install.sh | bash
```
Windows
```shell
❯ winget install yutu
```
Verifying Installation
Verify the integrity and provenance of `yutu` using its associated cryptographically signed attestations.
```shell
# 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 (Miffy) to automate YouTube workflows. The agent can retrieve, create, update, and delete YouTube content, with built-in YouTube growth strategy and SEO expertise.
Currently, the agent mode is under active development, only supports Google's Gemini models.
```shell
# console mode (default)
❯ yutu agent --api-key "YOUR_GEMINI_API_KEY"
# specify a different model
❯ yutu agent --model "google:gemini-3.7-flash" --api-key "YOUR_GEMINI_API_KEY"
# web mode with sub-launchers
❯ yutu agent --args "web api a2a webui" --api-key "YOUR_GEMINI_API_KEY"
# show available launcher args
❯ yutu agent --args ""
```
### Agent Flags
| Flag | Description | Default |
|---------------------|-----------------------------------------|--------------------------------------------|
| `-a, --args` | Launcher arguments as a single string | `console` |
| `-m, --model` | Model in `provider:modelName` format | `google:gemini-3.7-flash` |
| `--api-key` | API key for the model provider | |
| `-i, --instruction` | Override the built-in agent instruction | [INSTRUCTION.md](cmd/agent/INSTRUCTION.md) |
The `GOOGLE_GEMINI_BASE_URL` environment variable can optionally be set to use a custom Gemini API base URL.
## MCP Server
Before using `yutu` as an MCP server, make sure `yutu` is installed(see [Installation](#installation) section), and you have a valid `client_secret.json` and `youtube.token.json` files(refer to [Prerequisites](#prerequisites) section).
You can add `yutu` as an MCP server in VS Code or Cursor by clicking corresponding badge, or use the CLI commands below for your preferred tool.
[](https://insiders.vscode.dev/redirect/mcp/install?name=yutu&config=%7B%22type%22%3A%20%22stdio%22%2C%22command%22%3A%20%22yutu%22%2C%22args%22%3A%20%5B%22mcp%22%5D%2C%22env%22%3A%20%7B%22YUTU_CREDENTIAL%22%3A%20%22%2Fabsolute%2Fpath%2Fto%2Fclient_secret.json%22%2C%22YUTU_CACHE_TOKEN%22%3A%20%22%2Fabsolute%2Fpath%2Fto%2Fyoutube.token.json%22%7D%7D)
[](https://cursor.com/install-mcp?name=yutu&config=JTdCJTIyY29tbWFuZCUyMiUzQSUyMnl1dHUlMjBtY3AlMjIlMkMlMjJlbnYlMjIlM0ElN0IlMjJZVVRVX0NSRURFTlRJQUwlMjIlM0ElMjIlMkZhYnNvbHV0ZSUyRnBhdGglMkZ0byUyRmNsaWVudF9zZWNyZXQuanNvbiUyMiUyQyUyMllVVFVfQ0FDSEVfVE9LRU4lMjIlM0ElMjIlMkZhYnNvbHV0ZSUyRnBhdGglMkZ0byUyRnlvdXR1YmUudG9rZW4uanNvbiUyMiU3RCU3RA%3D%3D)
Claude Code
```shell
# Stdio mode
❯ claude mcp add -e YUTU_CREDENTIAL=/absolute/path/to/client_secret.json \
-e YUTU_CACHE_TOKEN=/absolute/path/to/youtube.token.json \
yutu -- yutu mcp
# HTTP mode (start the server first: yutu mcp --mode http --auth)
❯ claude mcp add --transport http \
--client-id YOUR_CLIENT_ID.apps.googleusercontent.com \
--client-secret \
yutu http://localhost:8216/mcp
```
Codex
```shell
# Stdio mode
❯ codex mcp add --env YUTU_CREDENTIAL=/absolute/path/to/client_secret.json \
--env YUTU_CACHE_TOKEN=/absolute/path/to/youtube.token.json \
yutu -- yutu mcp
# HTTP mode (start the server first: yutu mcp --mode http --auth)
❯ codex mcp add --url http://localhost:8216/mcp \
--oauth-client-id YOUR_CLIENT_ID.apps.googleusercontent.com \
yutu
```
Manual Configuration (VS Code, Cursor, OpenCode, etc.)
Add the following to your MCP settings. Remember to replace the values of `YUTU_CREDENTIAL` and `YUTU_CACHE_TOKEN` with correct paths on your local machine.
```json
{
"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 unified [skill](https://opencode.ai/docs/skills) that extends AI agents with YouTube domain knowledge, common workflows, and SEO best practices — covering videos, playlists, comments, channels, captions, subscriptions, and more.
```shell
❯ npx skills add https://github.com/eat-pray-ai/yutu/tree/main/skills/youtube
```
See [skills/youtube/SKILL.md](skills/youtube/SKILL.md) for the full list of supported operations.
## Usage
```shell
❯ yutu
yutu is a CLI, MCP server, and AI agent for YouTube that can automate almost all YouTube workflows.
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:
abuseReport Manage YouTube abuse reports
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
liveBroadcast Manage YouTube live broadcasts
liveChatBan Manage YouTube live chat bans
liveChatMessage Manage YouTube live chat messages
liveChatModerator Manage YouTube live chat moderators
liveStream Manage YouTube live streams
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
thirdPartyLink Manage YouTube third-party links
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.
```
## Features
Please refer to [FEATURES.md](docs/FEATURES.md) for more information.
## Contributing
Please refer to [CONTRIBUTING.md](docs/CONTRIBUTING.md) for more information.