# youtube-mcp-server gives a model ten read-only tools over the YouTube API

> The zubeid-youtube-mcp-server package is a Model Context Protocol server that exposes YouTube search, video details, transcripts, channel metadata and playlists as MCP tools, with a second API key for quota failover. It suits research and discovery workflows, and it is not a server for uploading or editing videos.

**ZubeidHendricks/youtube-mcp-server** — MCP Server for YouTube API, enabling video management, Shorts creation, and advanced analytics

- Repository: https://github.com/ZubeidHendricks/youtube-mcp-server
- Website: https://zubeidhendricks.github.io/youtube-mcp-server/
- Stars: 588 · Forks: 142
- Language: TypeScript
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/zubeidhendricks-youtube-mcp-server

## What the ten tools actually cover

The server exposes 10 MCP tools, and reading the table rather than the summary is instructive. The video tools are videos_getVideo, which takes a videoId and an optional parts list, and videos_searchVideos, which takes a query and a long list of optional filters. The transcript tool is transcripts_getTranscript, taking a videoId and an optional language. The channel tools are the bulk of the surface: channels_getChannel for one channel, channels_getChannels for a batch of channel IDs, channels_searchChannels to search by handle, name or query, channels_findCreators to discover creator channels from video mentions, and channels_listVideos for a channel's uploads. The playlist tools are playlists_getPlaylist and playlists_getPlaylistItems. Read that list against the package description, which mentions video management, Shorts creation and advanced analytics, and the gap is clear. Every documented tool reads. There is no upload, no edit, no comment, no subscription and no analytics endpoint. The description is broader than the tool surface, and if you are evaluating this for content management you will find the mismatch immediately.

## The search filters, and what indie_priority actually means

The optional parameters on videos_searchVideos are where the real work is, and they fall into four groups. Basic shaping: maxResults, order with values such as relevance or date, and publishedAfter and publishedBefore as ISO 8601 dates. Channel restriction by ID, plus a uniqueChannels boolean that returns only one video per unique channel. Subscriber band filters, channelMinSubscribers and channelMaxSubscribers, and activity filters, channelLastUploadAfter and channelLastUploadBefore. And a creatorOnly boolean that restricts results to channels heuristically classified as creators. The sortBy parameter is where the tool becomes opinionated, supporting relevance, subscribers_asc, subscribers_desc, indie_priority and recent_activity. The indie_priority mode is the interesting one for research, because sorting by relevance in a search API tends to return the largest channels, and a way to surface smaller channels by subscriber count is a different research question. Note the honest caveat that runs through all of it. The creator classification is a heuristic, not a fact from the API, so a creatorOnly filter is a best guess about whether a channel is a person or a brand, and the classification fields are part of the normalized metadata the channel response returns.

## Channel responses and the normalizedMetadata block

The channel tools return more than the raw API payload, and the difference is the enrichment layer. Responses to channels_getChannel now include latestVideoPublishedAt, and a normalizedMetadata object that carries country, defaultLanguage, joinedAt, customUrl, emailsFound, contactLinks, and the creator-versus-brand heuristic fields. The batch variant channels_getChannels takes an array of channel IDs, with parts and an includeLatestUpload boolean that defaults to true, which is what makes the latest upload timestamp available across a batch of channels. The enrichment is not cosmetic. A search tool that returns channels is only useful for prospecting if the caller can tell a small active channel from a dormant one, and the joinedAt and contactLinks fields are what let a downstream agent judge reachability and whether the channel is still being maintained. The cost is that this is the server's own interpretation of the API's output, so anything you build on it inherits the heuristic's error rate.

## Transcripts, and the language fallback chain

transcripts_getTranscript takes a videoId and an optional language code, and the fallback behaviour is documented precisely. The language falls back to the YOUTUBE_TRANSCRIPT_LANG environment variable, or to en. That last part matters in practice, because YouTube auto-generated transcripts exist in a range of languages and a request without an explicit language will silently return English even for a video whose spoken content was in another language. For research use, the correct move is to set the environment variable rather than to pass the parameter each time, and to be aware that the fallback means a wrong-language result is not an error but an empty-looking result. The transcript support comes from the youtube-transcript package, and the tool was fixed in the v1.0.2 release, which the release notes describe as a transcript fix alongside dependency upgrades. The v1.0.1 release was a STDIO transport fix and a switch to the MIT licence, which tells you that the transport and the licence both changed in the same week in July 2026.

## Installing into Claude Desktop, and where the keys go

The package is published on npm as zubeid-youtube-mcp-server and installs globally.

```bash
npm install -g zubeid-youtube-mcp-server
```

You then add it to the Claude Desktop configuration, which the documentation locates at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and at %APPDATA%\Claude\claude_desktop_config.json on Windows. The entry names the server, gives the command, and passes the API keys through an env block.

```json
{
  "mcpServers": {
    "zubeid-youtube-mcp-server": {
      "command": "zubeid-youtube-mcp-server",
      "env": {
        "YOUTUBE_API_KEY": "your_primary_youtube_api_key",
        "YOUTUBE_API_KEY2": "your_secondary_youtube_api_key",
```

The documentation says the keys come from the Google Cloud console, and the .env.example file spells out the failover design. The server tries key 1 first, then fails over to key 2 and key 3 on quota exhaustion, with YOUTUBE_API_KEY, YOUTUBE_API_KEY2 and YOUTUBE_API_KEY3 as the three variables, and an optional YOUTUBE_TRANSCRIPT_LANG for the default transcript language. Three keys is not a design choice you would invent for a single user, and it is a signal about who the tool is for. Anyone doing search-heavy research against the Data API will exhaust the daily quota of one key, and the failover is what keeps a long research session alive.

## The Docker path, and what the environment variables are for

The repository ships a Dockerfile, and its environment variables show that the server speaks two transports. The image is a two stage build on node:22-alpine, compiling TypeScript in the build stage and copying dist into a runtime stage that installs production dependencies only. The runtime sets NODE_ENV=production, and then the MCP variables: MCP_TRANSPORT=http, MCP_HOST=0.0.0.0, MCP_PORT=8088 and MCP_STATELESS=true. The port is exposed and there is a healthcheck that polls the ready endpoint every 30 seconds with a 5 second timeout, a 20 second start period and 3 retries. The distinction between the transports is the thing to understand. STDIO is the default way a local MCP server is launched by a desktop client, as the v1.0.1 release note suggests, and the HTTP transport with a stateless flag is what turns the same server into something you can run as a container behind a port. Setting MCP_HOST to 0.0.0.0 rather than the loopback address is the part to check carefully, because it is the difference between a service reachable from your machine and one reachable from the network.

## The package internals and the smoke test

The manifest describes a small TypeScript project with a clear split between the library and the executable. The main entry is dist/index.js, and the bin entry is dist/cli.js, so the package exposes both a module entry point and a command. The build script is tsc, the dev script runs nodemon over the TypeScript sources rebuilding and restarting, and prepublishOnly runs the build so a published tarball always contains compiled output. The files array limits what is shipped to dist, the README, and the LICENSE. The runtime dependencies are the MCP SDK at ^1.1.1, dotenv for environment loading, googleapis for the YouTube Data API client, and youtube-transcript for the transcript retrieval. The test script is not a unit test suite but a single smoke test file, node scripts/smoke-test.mjs, which is a reasonable choice for a server whose behaviour is mostly determined by what it returns from an external API. The repository also carries a .mcp.json.example for client configuration, a smithery.yaml for registry deployment, an llms.txt, a Dockerfile, and a checked-in tarball of the 1.0.0 release, which is unusual but harmless.

## Conclusion

Adopt youtube-mcp-server if you want a model to research YouTube, since the transcript tool and the channel filters are the substantive parts and the setup is one npm install plus a config entry. Do not adopt it expecting to manage or upload content, because the documented tool list is read only even though the package description mentions video management and Shorts creation, and the ten tools listed cover searching, reading transcripts, reading channel metadata and reading playlists. Verify two things first: that the quota behaviour works for your usage, since the server tries one key and fails over to the second and third on quota exhaustion, and that the creator classification is acceptable for your research, because several filters rely on channels being heuristically classified as creators rather than brands. The practical first step is to install the package globally, add it to the Claude Desktop configuration with your API keys, and confirm that a single search call returns results before wiring the filters.

## FAQ

### What tools does youtube-mcp-server expose?

It exposes 10 read-only MCP tools: videos_getVideo, videos_searchVideos, transcripts_getTranscript, channels_getChannel, channels_getChannels, channels_searchChannels, channels_findCreators, channels_listVideos, playlists_getPlaylist and playlists_getPlaylistItems.

### How do I install youtube-mcp-server for Claude Desktop?

Run npm install -g zubeid-youtube-mcp-server, then add an entry to the Claude Desktop configuration at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows, naming the command and passing the API keys in the env block.

### How does the server handle YouTube API quota exhaustion?

It tries the first key and fails over to the second and third on quota exhaustion. The .env.example file names the three variables YOUTUBE_API_KEY, YOUTUBE_API_KEY2 and YOUTUBE_API_KEY3, and the keys come from the Google Cloud console.

### How does youtube-mcp-server choose the transcript language?

The language parameter on transcripts_getTranscript falls back to the YOUTUBE_TRANSCRIPT_LANG environment variable, or to en if neither is set. The .env.example file lists YOUTUBE_TRANSCRIPT_LANG as an optional setting for the default transcript language.

### What does the creatorOnly filter do in youtube-mcp-server?

It restricts results to channels heuristically classified as creators rather than brands, a classification that is also reported in the normalizedMetadata of channel responses alongside country, joinedAt, customUrl, emailsFound and contactLinks.

### Can youtube-mcp-server run over HTTP instead of STDIO?

Yes. The Docker image sets MCP_TRANSPORT=http with MCP_HOST=0.0.0.0, MCP_PORT=8088 and MCP_STATELESS=true, and exposes port 8088 with a healthcheck against the ready endpoint.

## Sources

- [License: MIT](https://github.com/ZubeidHendricks/youtube-mcp-server/blob/main/LICENSE)
- [Project website](https://zubeidhendricks.github.io/youtube-mcp-server/)
- [README](https://github.com/ZubeidHendricks/youtube-mcp-server/blob/main/README.md)
- [Releases](https://github.com/ZubeidHendricks/youtube-mcp-server/releases)
- [ZubeidHendricks/youtube-mcp-server on GitHub](https://github.com/ZubeidHendricks/youtube-mcp-server)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zubeidhendricks-youtube-mcp-server