An MCP server that hands an agent the transcript of a YouTube video

One tool does the work, the second is opt-in

The server is described as a Model Context Protocol server that enables retrieval of transcripts from YouTube videos, giving direct access to video captions and subtitles through a simple interface. The tool surface is two tools, and the split is the most important design decision in the project. get_transcript is the core: it takes a YouTube video URL, a Shorts URL or a bare video ID, and returns the transcript. analyze_video is optional and requires a TwelveLabs API key, and it does something categorically different. Instead of reading what was said, it reasons over what is shown on screen using the Pegasus video understanding model, which the documentation says produces useful summaries and answers even for videos with little or no speech, with demos, gameplay, b-roll and music videos given as examples. The two tools are therefore not two versions of the same capability. One is cheap and always available, the other needs a key, a reachable file and a network round trip to another service.

Language fallback, timestamps and ad filtering

Three details of get_transcript decide whether it is useful in practice. The first is language handling. The lang parameter takes a language code such as ko or en, and the documentation says it automatically falls back to available languages if the requested language is not found. That fallback is the difference between a tool that works and a tool that returns an error on every Japanese video when the default is English. The second is include_timestamps, which defaults to false and, when enabled, prefixes segments with markers like [0:05] so a model can cite a moment rather than a paragraph. The third is strip_ads, which defaults to true and filters out sponsorships, ads and promotional content based on chapter markers. The default being true is the interesting choice. A reader asking for a summary of a sponsored video generally does not want the sponsor read, and a caption track that includes the ad break adds tokens without adding information. The cost is that the filter is heuristic, based on chapter markers, so a video with no chapters or with an unusual structure will not be filtered, and there is no switch to preview the raw track other than turning strip_ads off.

Pointing a client at the server

There are several documented install routes and the simplest is a configuration block. For Claude Desktop you add the server under mcpServers, running it through npx.

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": ["-y", "@kimtaeyoon83/mcp-server-youtube-transcript"]
    }
  }
}

The optional analysis tool is enabled by adding the TwelveLabs key in an env block on the same entry.

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "npx",
      "args": ["-y", "@kimtaeyoon83/mcp-server-youtube-transcript"],
      "env": {
        "TWELVELABS_API_KEY": "your-twelvelabs-api-key"
      }
    }
  }
}

The README also documents installing through Smithery for Claude Desktop automatically, which runs the smithery CLI against the package name, and installing through mcp-get, a command line tool for installing and managing MCP servers, invoked through npx with the package name. The repeated npx entry point is the pattern to note. The server is published as a package that a client can run directly, so there is no separate process for a user to supervise, and the same configuration works for any client that speaks stdio MCP.

The TwelveLabs path needs a real file, not a watch page

The analyze_video tool has one constraint that is worth reading twice, because it is the kind of thing that fails in a confusing way. The url parameter must be a publicly reachable direct video URL, such as an .mp4, .mov or .webm link or a pre-signed URL, and the documentation is explicit that a YouTube watch page URL will not work because it serves HTML rather than a raw video stream. TwelveLabs fetches the file server-side, so the model never sees the page. The other parameters are ordinary: a prompt instructing the model, defaulting to a general summary, a model choice between pegasus1.2 and pegasus1.5 with pegasus1.2 as the default, and max_tokens defaulting to 2048. The key comes from twelvelabs.io and the documentation mentions a generous free tier, with the key supplied through the TWELVELABS_API_KEY environment variable. The design intent is that the transcript tool works without the key and analysis is fully opt-in, which is the right order of priority for a tool whose main job is cheap text retrieval.

Building from source and running the evals

The development prerequisites are Node.js 18 or higher and npm or yarn, and the build sequence is the standard TypeScript one, with npm install to fetch dependencies, npm run build to compile and npm run watch for auto-rebuild. The tests run with npm test, and the package manifest shows the compile step is tsc followed by a chmod on the built files, with the prepare script running the build on install. The debugging story is handled by the MCP Inspector, invoked through npm run inspector, and the reason given is the honest one, that MCP servers communicate over stdio, which makes debugging difficult. The evaluation setup is the part worth copying. The evals package loads an MCP client that then runs the index.ts file, so there is no need to rebuild between tests, and environment variables are passed by prefixing the npx command.

OPENAI_API_KEY=your-key  npx mcp-eval src/evals/evals.ts src/index.ts

That last point matters more than it looks. An MCP server that is evaluated through a client rather than through direct function calls is being tested the way it will actually run, and the dependency list in the manifest includes mcp-evals alongside the MCP SDK and the TwelveLabs client, so the harness is a first class part of the project rather than a script someone kept locally.

What the server does not do, and where it breaks

Three limits. The first is the big one, and it is structural rather than a bug. The server reads caption tracks, and captions are a property of the video. A video with captions disabled by its author has no transcript, the documentation lists unavailable transcripts as one of the error cases it handles, and there is nothing the server can do about it. A workflow that assumes every video it sees is searchable will break, and the breakage looks like a tool failure rather than a missing caption. The second is the dependency on YouTube's own endpoints, which the documentation alludes to in the error handling section, where it lists YouTube API errors, language availability issues and network errors among the cases handled. Both the fetch path and the ad filtering depend on those endpoints behaving as expected. The third is that analyze_video does not work on YouTube URLs at all, so a team that wants visual understanding of a YouTube video has to get the raw file somewhere else first, and the documentation does not describe a path for doing that. The server's own key features list is honest about the transcript path, naming support for multiple video URL formats including Shorts, language specific retrieval with fallback, optional timestamps, built-in ad filtering, zero external dependencies for transcript fetching, and detailed metadata in the responses. The zero external dependencies claim is specifically about transcript fetching, and it is the reason the transcript tool works without any key.

Editorial conclusion

Adopt this server if your agent workflow is about reading what people said in a video rather than watching one, since the transcript tool is dependency free and the language fallback handles the common case of a video with no captions in the language you asked for. Skip it if you need visual understanding of a YouTube video, because analyze_video only accepts a direct video file URL and a watch page will not work, and skip it if your agent needs the audio track rather than the caption track, since the server reads captions, not sound. Before wiring it up, check that the videos you care about have captions at all, and keep the TwelveLabs key optional, since the transcript path works without it.

Frequently asked questions

Official sources

1. Issues
2. kimtaeyoon83/mcp-server-youtube-transcript on GitHub
3. License: MIT
4. README