# YouTube MCP Server (`seemuapps/youtube-mcp`) Actor

MCP server exposing YouTube tools. Transcript, metadata, thumbnails, video and audio download, channel email. For any AI agent or LLM client.

- **URL**: https://apify.com/seemuapps/youtube-mcp.md
- **Developed by:** [Andrew](https://apify.com/seemuapps) (community)
- **Categories:** Agents, MCP servers, Social media
- **Stats:** 7 total users, 3 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.00005 / actor start

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## YouTube MCP Server

The all-in-one MCP server for YouTube. Plug any AI agent - Claude, Cursor, ChatGPT, VS Code, or your own - into a single endpoint and pull live data from any YouTube video or channel: transcripts, metadata, thumbnails, full video and MP3 downloads, and channel contact emails.

### What you get

- **Full transcripts** - text plus timestamped segments in any available language, manual or auto-generated, with language fallback and a list of every track the video offers
- **Video metadata** - title, description, uploader and channel info, duration, view/like/comment counts, upload date, language, age limit, live status, categories, tags, chapters, top thumbnails
- **Thumbnail downloads** - every available size (maxres, sd, hq, mq, default) saved as JPGs in the run's storage
- **MP4 video downloads** - pick 360p, 720p, 1080p, 1440p, or "best available", saved straight to the run's storage
- **MP3 audio rips** - 128, 192, or 320 kbps, saved straight to the run's storage
- **Channel contact emails** - scans the About page plus recent video descriptions, deduplicates, filters out no-reply/fake addresses, and reports the source for every email
- **Bulk lookups** - query up to 10 videos in a single transcript or metadata call, up to 20 thumbnails, up to 10 channels for emails
- **One endpoint, six tools** - no glue code, no per-tool integrations, no scraping infrastructure to maintain

### Use cases

- AI agents and assistants that need YouTube data without building a custom scraper
- Podcast and content research - pull a transcript and metadata for any video in seconds
- Content reuse - turn a long video into a transcript, MP3, and thumbnail set ready for a blog post or social clip
- Archival and offline access - back up videos you have permission to use as MP4 or MP3
- Creator outreach and lead generation - pull contact emails from creators in a niche
- Competitor monitoring - track view counts, descriptions, and chapters across a list of videos

### Tools exposed

| Tool             | Returns                                                                                       |
|------------------|-----------------------------------------------------------------------------------------------|
| `get-transcript` | Transcript text + timestamped segments for up to 10 videos per call                           |
| `get-metadata`   | Title, description, uploader, channel, duration, counts, chapters, thumbnails, tags          |
| `get-thumbnail`  | JPG thumbnails saved to the run's Key-Value Store (up to 20 videos, 5 sizes each)             |
| `download-video` | A single MP4 saved to the run's Key-Value Store (single video per call, up to 2 GB)           |
| `download-mp3`   | A single MP3 saved to the run's Key-Value Store (single video per call, up to 500 MB)         |
| `get-email`      | Contact emails extracted from channel + recent video descriptions, up to 10 channels per call |

All saved files (thumbnails, MP4, MP3) come back as `fileUrl` fields in the response - fetch them with the same Apify API token you used to call the MCP server.

### How to use

Use Apify's hosted MCP gateway - it generates ready-to-paste config snippets for Claude Desktop, Cursor, VS Code, ChatGPT, and any other MCP-compatible client:

**[mcp.apify.com/?tools=seemuapps/youtube-mcp](https://mcp.apify.com/?tools=seemuapps/youtube-mcp)**

Open the link, sign in, and copy the snippet for your client.

#### Where to get your Apify API token

Go to **[console.apify.com/settings/integrations](https://console.apify.com/settings/integrations)** and copy your **Personal API token**. (Sign in or create a free account if you haven't already.)

The token authorizes calls to the MCP server, lets you fetch saved thumbnails / MP4s / MP3s from the run's Key-Value Store, and is what Apify uses to bill you for tool calls.

### Pricing (pay-per-event)

| Tool             | Event                  | Charged                                                       |
|------------------|------------------------|---------------------------------------------------------------|
| `get-transcript` | `transcript-extracted` | Once per video where a transcript was successfully returned   |
| `get-metadata`   | `metadata-extracted`   | Once per video where metadata was successfully returned       |
| `get-thumbnail`  | `thumbnails-fetched`   | Once per video where at least one thumbnail size was saved    |
| `download-video` | `video-downloaded`     | Once per MP4 successfully saved                               |
| `download-mp3`   | `audio-converted`      | Once per MP3 successfully saved                               |
| `get-email`      | `channel-scanned`      | Once per channel scanned                                      |
| `get-email`      | `email-found`          | Once per unique email returned                                |

Failed calls are not charged. Partial failures (e.g. one bad URL in a batch) are reported per-item without aborting the whole call.

### File size and download notes

- **Thumbnails** are tiny (a few KB to ~150 KB) and stored as JPGs.
- **Video downloads** are capped at 2 GB per file and 1 hour per video by default. Override `maxDurationSeconds` (set 0 to disable) for longer content. Higher resolutions and longer videos take longer - a 1440p hour-long video can take several minutes to fetch.
- **MP3 downloads** are capped at 500 MB per file and 1 hour per video by default. A typical 10-minute video at 192 kbps is ~14 MB.
- All saved files are stored in the run's default Key-Value Store. Each tool response includes a `fileUrl` you fetch with your Apify API token to retrieve the bytes.

### Notes

- Only **public** YouTube videos and channels are supported.
- Auto-generated captions are used when manual captions are not available; toggle `preferManualCaptions` on `get-transcript` to invert this.
- The default proxy mode is `residential`, which works for most YouTube content. Switch to `auto` if you want to try without a proxy first.

### Related YouTube actors

Part of a complete YouTube toolkit - explore the rest of the suite:

- [YouTube Channel Videos Scraper](https://apify.com/seemuapps/youtube-channel-videos-scraper) - List every video on a channel with metadata
- [YouTube Video Metadata Scraper](https://apify.com/seemuapps/youtube-video-metadata-scraper) - Bulk video metadata - views, tags, chapters, more
- [YouTube Transcript Scraper](https://apify.com/seemuapps/youtube-transcript-scraper) - Full transcripts and timestamped captions
- [YouTube Comment Insights](https://apify.com/seemuapps/youtube-comment-insights) - Sentiment, keywords, and topics from comments
- [YouTube Channel Growth Analyzer](https://apify.com/seemuapps/youtube-channel-growth-analyzer) - Growth metrics, cadence, and best posting time
- [YouTube Similar Channels Finder](https://apify.com/seemuapps/youtube-similar-channels-finder) - Find similar and competitor channels
- [YouTube Sponsorship & Brand Deal Tracker](https://apify.com/seemuapps/youtube-sponsorship-tracker) - Extract sponsors, brand deals, and promo codes
- [YouTube Creator Contact Finder](https://apify.com/seemuapps/youtube-creator-contact-finder) - Find a creator's email and social links
- [YouTube Email Scraper](https://apify.com/seemuapps/youtube-email-scraper) - Bulk-extract contact emails from channels
- [YouTube Thumbnail Downloader](https://apify.com/seemuapps/youtube-thumbnail-downloader) - Download video thumbnails in every size
- [YouTube Video Downloader](https://apify.com/seemuapps/youtube-video-downloader) - Download videos as MP4 up to 1440p
- [YouTube to MP3 Converter](https://apify.com/seemuapps/youtube-to-mp3) - Convert videos to MP3 audio (128-320 kbps)

# Actor input Schema

## `tool` (type: `string`):

Pick a tool to run and save results to the dataset, or leave empty to start the actor as an MCP Standby server.

## `videoUrl` (type: `string`):

Single YouTube video URL - required by download-video and download-mp3.

## `videoUrls` (type: `array`):

YouTube video URLs - used by get-transcript, get-metadata, get-thumbnail, and (optionally) get-email.

## `channelUrls` (type: `array`):

YouTube channel URLs or @handles - used by get-email. Up to 10 per call.

## `languages` (type: `array`):

BCP-47 language codes for get-transcript, in preference order (e.g. en, es, fr).

## `preferManualCaptions` (type: `boolean`):

get-transcript: when both manual and auto-generated captions exist for a language, use the human-written ones.

## `videoQuality` (type: `string`):

download-video: maximum resolution. The actor picks the highest MP4 available at or below this height.

## `audioQuality` (type: `string`):

download-mp3: MP3 bitrate. Higher = larger file, better quality.

## `maxDurationSeconds` (type: `integer`):

download-video / download-mp3: skip videos longer than this. Default 3600 (1 hour). Set 0 to disable.

## `maxVideosToScan` (type: `integer`):

get-email: number of recent videos to scan per channel for emails (0 = scan only the channel description).

## `proxyMode` (type: `string`):

Residential is the default and works for most YouTube content. Auto tries no proxy first, then datacenter, then residential.

## Actor input object example

```json
{
  "tool": "",
  "videoUrl": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
  "videoUrls": [
    "https://www.youtube.com/watch?v=jNQXAC9IVRw"
  ],
  "channelUrls": [
    "@mkbhd"
  ],
  "languages": [
    "en"
  ],
  "preferManualCaptions": true,
  "videoQuality": "720",
  "audioQuality": "192",
  "maxDurationSeconds": 3600,
  "maxVideosToScan": 5,
  "proxyMode": "residential"
}
```

# Actor output Schema

## `results` (type: `string`):

Records produced by the selected tool: transcripts (get-transcript), metadata (get-metadata), thumbnail manifests (get-thumbnail), download manifests (download-video, download-mp3), or channel email lookups (get-email). One record per row.

## `keyValueStore` (type: `string`):

Thumbnails (get-thumbnail), MP4 video files (download-video), and MP3 audio files (download-mp3) are saved here. Each result record includes the file URL.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "videoUrl": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
    "videoUrls": [
        "https://www.youtube.com/watch?v=jNQXAC9IVRw"
    ],
    "channelUrls": [
        "@mkbhd"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("seemuapps/youtube-mcp").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "videoUrl": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
    "videoUrls": ["https://www.youtube.com/watch?v=jNQXAC9IVRw"],
    "channelUrls": ["@mkbhd"],
}

# Run the Actor and wait for it to finish
run = client.actor("seemuapps/youtube-mcp").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "videoUrl": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
  "videoUrls": [
    "https://www.youtube.com/watch?v=jNQXAC9IVRw"
  ],
  "channelUrls": [
    "@mkbhd"
  ]
}' |
apify call seemuapps/youtube-mcp --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,seemuapps/youtube-mcp"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/r4V0UcVVhSoz3vTrW/builds/uCNg8pk1CqXedZ8qW/openapi.json