playbooks

home / mcp / youtube mcp server

YouTube MCP Server

YouTube MCP Server is an AI-powered solution designed to revolutionize your YouTube experience. It empowers users to search for YouTube videos, retrieve detailed transcripts, and perform semantic searches over video content—all without relying on the official API. By integrating with a vector database, this server streamlines content discovery.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "ia-programming-youtube-mcp": {
      "command": "C:\\Path\\To\\Your\\Project\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Path\\To\\Your\\Project\\server.py"
      ],
      "env": {
        "GOOGLE_API_KEY": "your_api_key_here"
      }
    }
  }
}

You can search YouTube, retrieve transcripts, store video data in a vector store, and perform semantic searches over transcripts using this MCP (Model Context Protocol) server. It exposes practical tools you can call from MCP clients to work with YouTube content in a privacy-friendly, code-driven way.

How to use

You will run the YouTube MCP Server locally and connect it to an MCP client. Once running, you can search for videos by query, fetch transcripts for a specific video, store video information and transcripts in a vector database, and then perform semantic searches over the stored transcripts. Use these tools through your MCP client by invoking them with natural language prompts or structured tool calls, such as asking for a tutorial video or requesting the transcript for a given URL, followed by a semantic search for topics like machine learning.

How to install

Prerequisites you need before installation: Python 3.8 or newer and the uv package manager. You also need a Google API key to generate embeddings used by the server.

# Create and activate a virtual environment using uv
uv venv
# On Windows:
.venv\Scripts\activate
# On Unix/MacOS:
source .venv/bin/activate

# Install dependencies
uv pip install -r requirements.txt

# Create your environment file with your Google API key
# Place this in the project root
GOOGLE_API_KEY=your_api_key_here

Configuration and running methods

There are two typical ways to run the MCP server locally. One is a direct method, and the other is configuring an MCP client (such as Claude) to start the server for you.

# Direct method using the built-in command
"youtube_direct": {
  "type": "stdio",
  "command": "uv",
  "args": ["run", "python", "server.py"],
  "env": {
    "GOOGLE_API_KEY": "your_api_key_here"
  }
}

Direct method start (inline example)

Start the server directly from your terminal using the uv workflow shown here.

uv run python server.py

Configure for Claude.app (Windows) and UV-based start

If you use Claude.app, you can specify a stdio MCP configuration that runs the server from a Windows path or via the uv workflow.

"youtube_winpy": {
  "type": "stdio",
  "name": "youtube_winpy",
  "command": "C:\\Path\\To\\Your\\Project\\.venv\\Scripts\\python.exe",
  "args": ["C:\\Path\\To\\Your\\Project\\server.py"],
  "env": {
    "GOOGLE_API_KEY": "your_api_key_here"
  }
}

Configure for Claude.app (Windows with uv)

Alternatively, configure Claude to run the server via uv by pointing to the project directory.

"youtube_uv_win": {
  "type": "stdio",
  "name": "youtube_uv_win",
  "command": "uv",
  "args": ["--directory", "C:\\Path\\To\\Your\\Project", "run", "server.py"],
  "env": {
    "GOOGLE_API_KEY": "your_api_key_here"
  }
}

Available tools and how to use them

The server exposes a set of tools you can call from an MCP client. These tools let you search YouTube, fetch transcripts, store data, and semantically search transcripts.

Debugging

If you run into issues, verify the following: the Google API key is correctly set in the environment, dependencies are installed, the server process is running and listening for connections, and any error messages in the server output point to a concrete problem to fix.

Troubleshooting

Common steps include rechecking the Google API key, reinstalling dependencies if needed, and ensuring the correct startup command is used in your MCP client configuration.

Contributing

Contributions are welcome. You can submit improvements or fixes by following standard contribution workflows for this project.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Available tools

search-youtube

Search for YouTube videos based on a query and return a list of results. Parameters include query and max_results.

get-transcript

Retrieve the transcript for a specified YouTube video given its URL.

store-video-info

Store video metadata and its transcript into the vector database for later semantic search.

search-transcripts

Perform a semantic search over stored video transcripts and return relevant results up to a defined limit.