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

Installation

Using uv (Recommended)

# 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

Using pip

pip install mcp_youtube_extract

From source

1. Clone the repository:

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

2. 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)

Usage

Running the MCP Server

# 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:

{
  "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:

1. Unit Tests (test_youtube_unit.py): Test core YouTube functionality with mocked APIs
2. Integration Tests (test_context_fix.py, test_with_api_key.py): Test full server functionality
3. 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

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

Support

If you encounter any issues or have questions, please:

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