mcp-youtube-extract

What is mcp_youtube_extract?

mcp_youtube_extract is an MCP (Model Context Protocol) server that facilitates the extraction of information from YouTube videos. It acts as a backend service that can be integrated with various clients to retrieve video metadata and transcripts, including both manually created and auto-generated ones. The project emphasizes comprehensive logging, robust error handling, and intelligent fallback logic for transcript retrieval.

How to use mcp_youtube_extract?

Installation

The easiest way to install is via PyPI:

pip install mcp-youtube-extract

Alternatively, you can use pipx for command-line tools:

pipx install mcp-youtube-extract

For development, you can install from source using uv:

git clone https://github.com/sinjab/mcp_youtube_extract.git
cd mcp_youtube_extract
uv sync --dev

Configuration

You need a YouTube Data API key. Create a .env file in the project root for development, or set the YOUTUBE_API_KEY environment variable for production.

Running the Server

After installation and configuration, run the server:

mcp_youtube_extract

Using the Tool

The server provides one main tool: get_yt_video_info. This tool takes a YouTube video ID and returns video metadata and transcripts.

Client Configuration

To use with a client, configure your client's mcpServers settings. For PyPI installation:

{
  "mcpServers": {
    "mcp_youtube_extract": {
      "command": "mcp_youtube_extract",
      "env": {
        "YOUTUBE_API_KEY": "your_youtube_api_key"
      }
    }
  }
}

Key Features of mcp_youtube_extract

MCP Server: A fully functional MCP server with tools for YouTube information extraction.
Comprehensive Logging: Detailed logging for debugging and monitoring.
Error Handling: Robust error handling with fallback logic for transcripts.
YouTube Integration: Extracts video information (title, description, channel, publish date) and transcripts (manual and auto-generated).
Easy Installation: Available on PyPI for straightforward installation.
Flexible Configuration: Supports environment variables for API keys.

Use Cases of mcp_youtube_extract

Content Analysis: Automatically extract video details and transcripts for content analysis platforms.
AI/ML Applications: Provide structured YouTube data for training and inference in AI/ML models.
Data Archiving: Systematically collect and store YouTube video information for archival purposes.
Research: Facilitate research by programmatically accessing YouTube video data.
Custom YouTube Tools: Build custom applications that require detailed YouTube video information and transcripts.

FAQ about mcp_youtube_extract

Q: Do I need a YouTube API key? A: Yes, a YouTube Data API key is required to use this MCP server. Instructions for obtaining one are provided in the documentation.

Q: Is there a free tier for the YouTube Data API? A: Yes, the YouTube Data API has a free tier of 10,000 units per day, which is generally sufficient for most use cases.

Q: How can I restrict my API key for security? A: It is highly recommended to restrict your API key to only the YouTube Data API v3 in the Google Cloud Console.

Q: How do I run tests for mcp_youtube_extract? A: You can run tests using uv run pytest. There are unit tests, integration tests, and a standalone inspection script.

Q: What kind of transcripts can be extracted? A: The tool supports extracting both manually created and auto-generated transcripts with intelligent fallback logic.

MCP YouTube Extract

A Model Context Protocol (MCP) server for YouTube operations, demonstrating core MCP concepts including tools and logging.

Features

MCP Server: A fully functional MCP server with:
- Tools: Extract information from YouTube videos including metadata and transcripts
- Comprehensive Logging: Detailed logging throughout the application
- Error Handling: Robust error handling with fallback logic for transcripts
YouTube Integration: Built-in YouTube API capabilities:
- Extract video information (title, description, channel, publish date)
- Get video transcripts with intelligent fallback logic
- Support for both manually created and auto-generated transcripts

📦 Available on PyPI

This package is now available on PyPI! You can install it directly with:

pip install mcp-youtube-extract

Visit the package page: mcp-youtube-extract on PyPI

Installation

Quick Start (Recommended)

The easiest way to get started is to install from PyPI:

pip install mcp-youtube-extract

Or using pipx (recommended for command-line tools):

pipx install mcp-youtube-extract

This will install the latest version with all dependencies. You can then run the MCP server directly:

mcp_youtube_extract

Using uv (Development)

For development or if you prefer uv:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and install the project
git clone https://github.com/sinjab/mcp_youtube_extract.git
cd mcp_youtube_extract

# Install dependencies (including dev dependencies)
uv sync --dev

# Set up your API key for development
cp .env.example .env
# Edit .env and add your YouTube API key

From source

Clone the repository:

git clone https://github.com/sinjab/mcp_youtube_extract.git
cd mcp_youtube_extract

Install in development mode:
```
uv sync --dev
```

Configuration

Environment Variables

For development, create a .env file in the project root with your YouTube API key:

# YouTube API Configuration
YOUTUBE_API_KEY=your_youtube_api_key_here

For production, set the environment variable directly in your system:

export YOUTUBE_API_KEY=your_youtube_api_key_here

Required:

YOUTUBE_API_KEY: Your YouTube Data API key (required for video metadata)

Getting Your YouTube API Key

To use this MCP server, you'll need a YouTube Data API key. Here's how to get one:

Step 1: Create a Google Cloud Project

Go to the Google Cloud Console
Click "Select a project" at the top of the page
Click "New Project" and give it a name (e.g., "MCP YouTube Extract")
Click "Create"

Step 2: Enable the YouTube Data API

In your new project, go to the API Library
Search for "YouTube Data API v3"
Click on it and then click "Enable"

Step 3: Create API Credentials

Go to the Credentials page
Click "Create Credentials" and select "API Key"
Your new API key will be displayed - copy it immediately
Click "Restrict Key" to secure it (recommended)

Step 4: Restrict Your API Key (Recommended)

In the API key settings, click "Restrict Key"
Under "API restrictions", select "Restrict key"
Choose "YouTube Data API v3" from the dropdown
Click "Save"

Step 5: Set Up Billing (Required)

Go to the Billing page
Link a billing account to your project
Note: YouTube Data API has a free tier of 10,000 units per day, which is typically sufficient for most use cases

API Key Usage Limits

Free Tier: 10,000 units per day
Cost: $5 per 1,000 units after free tier
Typical Usage:
- Getting video info: ~1 unit per request
- Getting transcripts: ~1 unit per request
- Most users stay well within the free tier

Security Best Practices

Never commit your API key to version control
Use environment variables as shown in the configuration section
Restrict your API key to only the YouTube Data API
Monitor usage in the Google Cloud Console

Usage

Running the MCP Server

Using PyPI Installation (Recommended)

# Install from PyPI
pip install mcp-youtube-extract

# Run the server
mcp_youtube_extract

Using Development Setup

# Using uv
uv run mcp_youtube_extract

# Or directly
python -m mcp_youtube_extract.server

Running Tests

# Run all pytest tests
uv run pytest

# Run specific pytest test
uv run pytest tests/test_with_api_key.py

# Run tests with coverage
uv run pytest --cov=src/mcp_youtube_extract --cov-report=term-missing

Note: The tests/ directory contains 4 files:

test_context_fix.py - Pytest test for context API fallback functionality
test_with_api_key.py - Pytest test for full functionality with API key
test_youtube_unit.py - Unit tests for core YouTube functionality
test_inspector.py - Standalone inspection script (not a pytest test)

Test Coverage: The project currently has 62% overall coverage with excellent coverage of core functionality:

youtube.py: 81% coverage (core business logic)
logger.py: 73% coverage (logging utilities)
server.py: 22% coverage (MCP protocol handling)
__init__.py: 100% coverage (package initialization)

Running the Inspection Script

The test_inspector.py file is a standalone script that connects to the MCP server and validates its functionality:

# Run the inspection script to test server connectivity and functionality
uv run python tests/test_inspector.py

This script will:

Connect to the MCP server
List available tools, resources, and prompts
Test the get_yt_video_info tool with a sample video
Validate that the server is working correctly

Using the YouTube Tool

The server provides one main tool: get_yt_video_info

This tool takes a YouTube video ID and returns:

Video metadata (title, description, channel, publish date)
Video transcript (with fallback logic for different transcript types)

Example Usage:

# Extract video ID from YouTube URL: https://www.youtube.com/watch?v=dQw4w9WgXcQ
video_id = "dQw4w9WgXcQ"
result = get_yt_video_info(video_id)

Client Configuration

To use this MCP server with a client, add the following configuration to your client's settings:

Using PyPI Installation (Recommended)

{
  "mcpServers": {
    "mcp_youtube_extract": {
      "command": "mcp_youtube_extract",
      "env": {
        "YOUTUBE_API_KEY": "your_youtube_api_key"
      }
    }
  }
}

Using Development Setup

{
  "mcpServers": {
    "mcp_youtube_extract": {
      "command": "uv",
      "args": [
        "--directory",
        "<your-project-directory>",
        "run",
        "mcp_youtube_extract"
      ],
      "env": {
        "YOUTUBE_API_KEY": "your_youtube_api_key"
      }
    }
  }
}

Development

Project Structure

mcp_youtube_extract/
├── src/
│   └── mcp_youtube_extract/
│       ├── __init__.py
│       ├── server.py          # MCP server implementation
│       ├── youtube.py         # YouTube API utilities
│       └── logger.py          # Logging configuration
├── tests/
│   ├── __init__.py
│   ├── test_context_fix.py    # Context API fallback tests
│   ├── test_inspector.py      # Server inspection tests
│   ├── test_with_api_key.py   # Full functionality tests
│   └── test_youtube_unit.py   # Unit tests for core functionality
├── logs/                      # Application logs
├── .env                       # Environment variables (create from .env.example)
├── .gitignore                 # Git ignore rules (includes coverage files)
├── pyproject.toml
├── LICENSE                    # MIT License
└── README.md

Testing Strategy

The project uses a comprehensive testing approach:

Unit Tests (test_youtube_unit.py): Test core YouTube functionality with mocked APIs
Integration Tests (test_context_fix.py, test_with_api_key.py): Test full server functionality
Manual Validation (test_inspector.py): Interactive server inspection tool

Error Handling

The project includes robust error handling:

Graceful API failures: Returns appropriate error messages instead of crashing
Fallback logic: Multiple strategies for transcript retrieval
Consistent error responses: Standardized error message format
Comprehensive logging: Detailed logs for debugging and monitoring

Building

# Install build dependencies
uv add --dev hatch

# Build the package
uv run hatch build

License

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Getting Started

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Support

If you encounter any issues or have questions, please:

Check the existing issues
Create a new issue with detailed information about your problem
Include logs and error messages when applicable

mcp-youtube-extract Overview

What is mcp_youtube_extract?

How to use mcp_youtube_extract?

Installation

Configuration

Running the Server

Using the Tool

Client Configuration

Key Features of mcp_youtube_extract

Use Cases of mcp_youtube_extract

FAQ about mcp_youtube_extract

mcp-youtube-extract's README

MCP YouTube Extract

Features

📦 Available on PyPI

Installation

Quick Start (Recommended)

Using uv (Development)

From source

Configuration

Environment Variables

Getting Your YouTube API Key

Step 1: Create a Google Cloud Project

Step 2: Enable the YouTube Data API

Step 3: Create API Credentials

Step 4: Restrict Your API Key (Recommended)

Step 5: Set Up Billing (Required)

API Key Usage Limits

Security Best Practices

Usage

Running the MCP Server

Using PyPI Installation (Recommended)

Using Development Setup

Running Tests

Running the Inspection Script

Using the YouTube Tool

Client Configuration

Using PyPI Installation (Recommended)

Using Development Setup

Development

Project Structure

Testing Strategy

Error Handling

Building

License

Contributing

Getting Started

Support

mcp-youtube-extract Reviews

Actions

mcp-youtube-extract's Information