youtube-analytics-mcp

Локальный MCP-сервер только для чтения, который даёт Claude доступ к приватным данным Analytics вашего YouTube-канала — просмотры, время просмотра, удержание, подписчики, источники трафика, демография аудитории, доход и показы миниатюр/CTR. Не только то, что уже может видеть любой публичный API-ключ.

Ничто в этом сервере не может редактировать, загружать, публиковать или удалять что-либо на вашем канале. Полный обзор безопасности см. в SECURITY.md.

Требования

• Node.js 22+

• Учётная запись Google, которая владеет (или управляет) каналом YouTube, для которого нужны данные

• macOS, Linux или WSL (браузерный процесс npm run auth использует команду open)

Related MCP server: youtube-mcp-server

Чек-лист настройки

Выполняйте по порядку. Шаги 1–4 выполняются в Google Cloud Console; шаги 5–8 — на вашем компьютере.

1. Создайте проект Google Cloud

Перейдите на console.cloud.google.com и создайте новый проект (или выберите существующий, с которым вам удобно работать).

2. Включите три API

В вашем проекте перейдите в APIs & Services → Library и включите каждый из них:

• YouTube Data API v3

• YouTube Analytics API

• YouTube Reporting API (нужен только для показов миниатюр/CTR — см. ниже)

3. Настройте экран согласия OAuth

Перейдите в APIs & Services → OAuth consent screen.

• Тип пользователя: External (если у вас нет аккаунта Google Workspace, в этом случае Internal тоже подойдёт)

• Заполните обязательные поля: название приложения / email для поддержки

• Добавьте области Analytics при появлении запроса (или пропустите — приложение запрашивает их напрямую, этот экран просто должен существовать)

• Опубликуйте приложение в Production. Это шаг, который пропускают, а затем упираются в стену: приложения, оставленные в режиме «Testing», разрешают вход только с аккаунтов, которые вы явно добавили как тестовых пользователей, и их refresh-токены истекают через 7 дней, что означает необходимость повторять шаг 6 каждую неделю. Публикация в Production (без отправки на проверку Google) подходит для личного инструмента — Google покажет предупреждение «unverified app» при входе, и вы нажмёте Advanced → Go to [название вашего приложения] (unsafe), чтобы продолжить. Это ожидаемо и безопасно для вашего собственного приложения.

4. Создайте учётные данные OAuth

Перейдите в APIs & Services → Credentials → Create Credentials → OAuth client ID.

• Тип приложения: Desktop app

• Дайте ему любое имя

• Скопируйте сгенерированные Client ID и Client Secret — они понадобятся на шаге 5

Здесь не нужно регистрировать redirect URI; этот сервер при авторизации привязывает эфемерный локальный порт, и Google принимает любой loopback-адрес для клиентов типа Desktop.

5. Установка и сборка

git clone <this-repo-url>
cd youtube-analytics-mcp
npm install
npm run build

6. Настройка учётных данных

cp .env.example .env

Отредактируйте .env и вставьте Client ID / Client Secret с шага 4:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

.env находится в .gitignore — он никогда не попадёт в коммит. Необязательные настройки:

• GOOGLE_API_KEY — не требуется ни для одного текущего инструмента, оставьте пустым, если не расширяете сервер самостоятельно.

• REVENUE_CURRENCY — по умолчанию USD. Установите валюту выплат AdSense (например, BRL), если хотите видеть суммы дохода в этой валюте; Google конвертирует на стороне сервера.

7. Авторизация

npm run auth

Это откроет браузер для входа в Google и сохранит refresh-токен в ~/.youtube-analytics-mcp/token.json (права доступа ограничены только вашим пользователем, файл никогда не попадает в репозиторий). Это нужно сделать только один раз — в дальнейшем сервер автоматически обновляет access-токен.

Проверьте, что всё работает:

npm run auth:status

Вы должны увидеть Authenticated и название вашего канала.

8. Подключите Claude Code

Добавьте в конфигурацию MCP, используя абсолютный путь к dist/index.js этого проекта:

{
  "mcpServers": {
    "youtube-analytics-channel": {
      "command": "node",
      "args": ["/absolute/path/to/youtube-analytics-mcp/dist/index.js"]
    }
  }
}

Перезапустите Claude Code (или перезагрузите MCP-серверы) — и вы увидите доступные инструменты ниже.

Доступные инструменты

Примечание о показах и CTR

YouTube не предоставляет показы миниатюр или CTR через интерактивный Analytics API (reports.query) ни при какой комбинации измерений/фильтров — это было проверено напрямую через API, а не взято из документации. Эти данные существуют только в массовом «Reach report» YouTube — отдельном асинхронном API заданий:

1. Первый вызов get_impressions_and_ctr регистрирует в Google повторяющееся задание отчёта.

2. Google требуется 24–48 часов, чтобы создать первый отчёт, затем он продолжает создавать новые примерно ежедневно.

3. Каждый вызов get_impressions_and_ctr (или get_top_videos, отсортированного по показам/CTR) синхронизирует любые новые доступные отчёты в локальный кэш в ~/.youtube-analytics-mcp/reach-cache.json, а затем отвечает из этого кэша.

Пока первый отчёт не готов, эти инструменты возвращают impressions: 0, impressionsCtr: null и note с объяснением. Это ожидаемо при первом использовании, а не ошибка.

Устранение неполадок

• «Access blocked» во время npm run auth: ваш экран согласия OAuth всё ещё в режиме Testing. Вернитесь к шагу 3 и либо добавьте свой аккаунт как тестового пользователя, либо опубликуйте приложение в Production.

• NotAuthenticatedError при запуске сервера: выполните npm run auth.

• Доход всегда 0: либо канал не монетизирован, либо числа действительно нулевые за этот период. Инструмент никогда не выдумывает доход — проверьте поле available в get_revenue_analytics, чтобы отличить реальную ошибку доступа от настоящих нулей.

• get_impressions_and_ctr / отсортированный по показам get_top_videos ничего не возвращают: проверьте dataCoverage в ответе. Если earliestDate равен null, задание массового отчёта ещё не создало первый отчёт (может занять до 48 часов после самого первого вызова).

Тестирование

npm test

Запускает модульные тесты (встроенный тестовый раннер Node), покрывающие проверку дат/периодов, разбор длительности ISO-8601, разбор CSV, сопоставление строк отчёта Analytics и математику сравнения периодов (включая крайний случай деления на ноль). Это только тесты чистых функций — они не имитируют живые вызовы Google API или обновление OAuth-токена; эти пути были проверены вручную на реальном канале во время разработки.

Безопасность

Полную модель угроз и обзор OWASP Top 10 см. в SECURITY.md. Кратко: всё только для чтения, все секреты остаются на вашем компьютере вне репозитория, и каждое пользовательское значение, попадающее в вызов Google API, сначала проверяется.

Лицензия

MIT — см. LICENSE.