# youtube-mcp-server

[![CI](https://github.com/a-shipilo/youtube-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/a-shipilo/youtube-mcp-server/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

MCP-сервер для **вашего собственного YouTube-канала**: Claude читает комментарии, готовит ответы,
модерирует, смотрит аналитику, загружает и правит видео. Ответы, модерация, загрузка и правка выполняются
только после вашего подтверждения.
Сервер запускается через `uvx` прямо из GitHub, устанавливать ничего не нужно.

*English: an open-source MCP server for your own YouTube channel: read comment threads, reply and moderate,
query YouTube Analytics, upload videos (resumable, multi-GB) with a thumbnail and subtitles and edit them
(every write needs your confirmation). Run it with
`uvx --from git+https://github.com/a-shipilo/youtube-mcp-server youtube-mcp-server`.*

## Возможности

| Инструмент | Что делает | Квота |
|---|---|---|
| `channel` | канал: название, @handle, подписчики, просмотры, число видео | 1 |
| `videos` | последние загрузки (включая Shorts): длительность, доступ, просмотры, лайки, комментарии | 2+ |
| `comments` | ветки комментариев к видео или всему каналу, с ответами и названием видео | 1 за страницу |
| `comment_thread` | одна ветка со всеми ответами | 1–2 |
| `reply` | ответ в ветку от имени канала, **с подтверждением** | 50 |
| `edit_reply` | правка своего ответа, **с подтверждением** | 50 |
| `moderate` | одобрить, отправить на проверку или скрыть комментарии, по желанию заблокировать авторов, **с подтверждением** | 50 |
| `upload_video` | загрузка видео с компьютера (по частям, с докачкой) с обложкой и субтитрами, по умолчанию private, **с подтверждением** | 1 загрузка из 100 в сутки + 50 за обложку + 400 за субтитры |
| `update_video` | правка загруженного видео: название, описание, теги, категория, доступ, обложка, ещё одна дорожка субтитров, **с подтверждением** | 51 + 50 за обложку + 400 за субтитры |
| `analytics` | готовые отчёты: итоги, по дням, топ видео, источники трафика, поисковые запросы, удержание, страны, устройства, демография | 1 |
| `analytics_query` | произвольный `reports.query` к YouTube Analytics API | 1 |
| `confirm_action`, `cancel_action` | подтвердить или отменить подготовленную операцию | — |

- `comments` по умолчанию показывает ветки, где **последнее слово не за каналом**: новые комментарии
  и уточняющие вопросы в старых ветках. `show=unanswered` — только ветки без ответа канала, `show=all` — все.
  `status=heldForReview` или `likelySpam` открывает очереди проверки из Студии.
- Отвечать можно только в ветку (на комментарий верхнего уровня). Чтобы обратиться к участнику ветки,
  начните ответ с его @имени.
- Лайкать комментарии и ставить им сердечки YouTube API не позволяет.
- Квота YouTube API — 10 000 единиц в сутки, то есть около 200 ответов. Чтение почти бесплатное.
  Загрузки видео считаются отдельно: до 100 в сутки.
- Данные аналитики отстают от текущей даты на 2–3 дня.

### Подтверждение записи

`reply`, `edit_reply`, `moderate`, `upload_video` и `update_video` ничего не делают сразу: сначала вы видите
предпросмотр (чей комментарий и текст ответа, список комментариев; для видео — файл и его размер, название,
начало описания, теги, доступ, обложку, субтитры и расход квоты, для правки — что было и что станет).

- В клиентах с поддержкой elicitation (Claude Code) появляется диалог подтверждения.
- В остальных (Claude Desktop) инструмент возвращает предпросмотр и одноразовый `confirmation_id`,
  Claude показывает предпросмотр в чате и вызывает `confirm_action` только после вашего согласия.
  Неподтверждённая операция истекает через 15 минут.

Режим задаёт `YOUTUBE_CONFIRM_MODE`: `auto` (по умолчанию: диалог, если клиент умеет, иначе `confirmation_id`),
`elicitation` или `token`.

### Загрузка и правка видео

- `upload_video` берёт файл с диска (абсолютный путь), название, описание, теги, категорию, язык и доступ.
  Доступ по умолчанию **private**: видео видно только вам, опубликовать его можно потом в Студии или через
  `update_video` с `privacy=public`. `publish_at` ставит отложенную публикацию.
- Файл уходит по [resumable-протоколу](https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol)
  кусками по 32 МБ: после обрыва связи или ошибки 5xx загрузка продолжается с места, где YouTube остановился.
  Клиенты с поддержкой progress видят ход загрузки.
- Обложка — JPEG или PNG до 2 МБ (`thumbnails.set`; YouTube требует подтверждённый канал). Субтитры — `.srt`
  с таймкодами (`captions.insert`). Если обложка или субтитры не прошли, видео всё равно остаётся загруженным,
  а в ответе написано, что не получилось: обложку можно поставить ещё раз через `update_video`.
- Если файл изменился между предпросмотром и подтверждением, загрузка не начнётся.
- `update_video` меняет только указанные поля и переносит остальные как есть (YouTube заменяет раздел видео
  целиком, поэтому сервер перечитывает видео прямо перед правкой).

## Установка

Нужен установленный [uv](https://docs.astral.sh/uv/getting-started/installation/)
(`brew install uv` на macOS).

### 1. Создайте OAuth-клиент в Google Cloud

1. Откройте [console.cloud.google.com](https://console.cloud.google.com) и создайте проект.
2. **APIs & Services → Library**: включите **YouTube Data API v3** и **YouTube Analytics API**.
3. **Google Auth Platform → Get started**: название приложения, ваша почта, тип **External**.
4. **Audience → Publish app**. В статусе *Testing* Google отзывает доступ через 7 дней.
   Для личного использования проверка приложения не нужна: при входе Google просто предупредит,
   что приложение не проверено.
5. **Clients → Create client**, тип **Desktop app**. Скачайте JSON и положите его в папку сервера:
   `~/.config/youtube-mcp-server/` (или в свою, см. `YOUTUBE_MCP_DIR`).

### 2. Разрешите доступ к каналу

> **Обновление до 0.3.0.** Для загрузки видео сервер теперь запрашивает ещё право `youtube.upload`.
> Пройдите авторизацию заново (команда ниже), затем обновите `YOUTUBE_REFRESH_TOKEN` в настройках плагина
> (и в менеджере паролей): `youtube-mcp-server credentials` покажет новое значение. Старый доступ с
> `youtube.force-ssl` Google по документации тоже пускает к загрузке, но если инструменты ответят
> «не хватает прав», дело в нём.

```bash
uvx --from git+https://github.com/a-shipilo/youtube-mcp-server youtube-mcp-server auth
```

Откроется браузер. Выберите аккаунт канала (если канал на бренд-аккаунте, выберите именно его),
на экране «Google hasn't verified this app» нажмите **Advanced → Go to …** и разрешите доступ.
Команда сохранит `token.json` рядом с JSON клиента и покажет канал.

Проверить доступ позже:

```bash
uvx --from git+https://github.com/a-shipilo/youtube-mcp-server youtube-mcp-server check
```

### 3. Подключите сервер

#### Claude Code: плагин

Репозиторий — ещё и маркетплейс плагинов Claude Code с плагином `youtube`. Доступ к каналу плагин хранит
в своих настройках (секретные поля — в системной связке ключей), а не в файлах.

1. Покажите значения доступа (после шага 2):

   ```bash
   uvx --from git+https://github.com/a-shipilo/youtube-mcp-server youtube-mcp-server credentials
   ```

   Команда выведет `YOUTUBE_CLIENT_ID`, `YOUTUBE_CLIENT_SECRET` и `YOUTUBE_REFRESH_TOKEN`. Сохраните их
   в менеджере паролей: на другом компьютере повторять авторизацию не придётся.

2. Добавьте маркетплейс и поставьте плагин:

   ```bash
   claude plugin marketplace add a-shipilo/youtube-mcp-server
   claude plugin install youtube@youtube-mcp-server
   ```

   Или в Claude Code: `/plugin` → **Marketplaces** → добавить `a-shipilo/youtube-mcp-server`, затем
   установить `youtube`. При включении плагин спросит три значения из шага 1.

3. После этого `token.json` можно удалить: плагину он не нужен.

Плагин подтверждает ответы, модерацию, загрузку и правку видео в чате (`YOUTUBE_CONFIRM_MODE=token`). Инструменты называются
`mcp__plugin_youtube_youtube__*`.

#### Claude Code: без плагина

```bash
claude mcp add youtube -s user -- uvx --from git+https://github.com/a-shipilo/youtube-mcp-server@v0.3.0 youtube-mcp-server
```

С папкой не по умолчанию добавьте `-e YOUTUBE_MCP_DIR=/путь/к/папке` перед `--`.

#### Claude Desktop

1. Откройте **Settings → Developer → Edit Config**. Откроется файл `claude_desktop_config.json`.
2. Добавьте сервер в `mcpServers`:

```json
{
  "mcpServers": {
    "youtube": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/a-shipilo/youtube-mcp-server@v0.3.0",
        "youtube-mcp-server"
      ]
    }
  }
}
```

3. Полностью перезапустите Claude Desktop.

`@v0.3.0` фиксирует версию. Чтобы всегда брать последнюю версию из `main`, уберите `@v0.3.0`.
Для обновления добавьте в `args` перед `--from` флаг `--refresh`.

Если в логах `spawn uvx ENOENT`, укажите полный путь к uvx (узнать его: `which uvx`),
например `"command": "/opt/homebrew/bin/uvx"`.

## Настройки

| Переменная | По умолчанию | Описание |
|---|---|---|
| `YOUTUBE_MCP_DIR` | `~/.config/youtube-mcp-server` | папка с JSON OAuth-клиента и `token.json` |
| `YOUTUBE_CLIENT_ID`, `YOUTUBE_CLIENT_SECRET`, `YOUTUBE_REFRESH_TOKEN` | — | доступ к каналу вместо `token.json` (их передаёт плагин); значения показывает `credentials` |
| `YOUTUBE_CONFIRM_MODE` | `auto` | как подтверждаются ответы, модерация, загрузка и правка видео: `auto`, `elicitation`, `token` |

Без авторизации сервер всё равно стартует, а инструменты вернут понятную ошибку с командой `auth`.

## Команды

| Команда | Что делает |
|---|---|
| `youtube-mcp-server` | запускает MCP-сервер (stdio) |
| `youtube-mcp-server auth [--client-secret PATH]` | разрешает доступ к каналу в браузере и сохраняет его |
| `youtube-mcp-server check` | показывает канал, к которому есть доступ |
| `youtube-mcp-server credentials` | выводит сохранённый доступ как `YOUTUBE_CLIENT_ID`, `YOUTUBE_CLIENT_SECRET`, `YOUTUBE_REFRESH_TOKEN` |
| `youtube-mcp-server --version` | версия |

## Privacy

*Конфиденциальность.* Сервер работает на вашем компьютере, у него нет своего бэкенда, аналитики или телеметрии.

- **Куда уходят запросы.** Только в Google: YouTube Data API, YouTube Analytics API и OAuth
  (`googleapis.com`, `youtubeanalytics.googleapis.com`, `oauth2.googleapis.com`). Никаким третьим
  сторонам сервер данные канала не передаёт.
- **Где хранится доступ.** Refresh token лежит только локально: в `token.json` в `YOUTUBE_MCP_DIR`,
  с правами `600` (папка — `700`), или, с плагином Claude Code, в настройках плагина. Access token живёт в памяти процесса и на диск не пишется.
  Сервер не логирует комментарии, ответы и статистику.
- **Что видит MCP-клиент.** Результаты инструментов (комментарии, статистика) получает клиент, который
  их вызвал, например Claude, и они попадают в ваш разговор с моделью по правилам этого клиента.
- **Права.** Сервер запрашивает `youtube.force-ssl` (комментарии, правка видео, субтитры), `youtube.upload`
  (загрузка видео и обложек) и `yt-analytics.readonly`. Ответы, модерация, загрузка и правка видео выполняются
  только после вашего подтверждения.
- **Файлы видео.** `upload_video` и `update_video` читают с диска только указанные файлы и отправляют их только
  в YouTube (`www.googleapis.com/upload`).
- **Как отозвать доступ.** Удалите `token.json` (или плагин) и отзовите доступ приложения на
  [myaccount.google.com/permissions](https://myaccount.google.com/permissions).

*English: the server runs locally and talks only to Google APIs; it has no backend or telemetry. The refresh
token is stored only on your machine (`token.json`, mode 600). Tool results go to the MCP client that called
the tool. Revoke access at myaccount.google.com/permissions.*

## Разработка

```bash
git clone https://github.com/a-shipilo/youtube-mcp-server.git
cd youtube-mcp-server
uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check .
```

Локальная отладка в [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash
npx @modelcontextprotocol/inspector uv run youtube-mcp-server
```

## Лицензия

[MIT](LICENSE)