youtube-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

YouTube MCP Server is a Model Context Protocol (MCP) server implementation that enables AI language models to interact with YouTube content. It provides tools for accessing video information, transcripts, channel data, and playlist management through standardized MCP interfaces.

Development Commands

# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

# Start the server
npm start

# Development mode with auto-rebuild and hot reload
npm run dev

# Publish to npm (runs build first)
npm run prepublishOnly

Architecture

Core Structure

The project uses a service-based architecture with the following layers:

1. Entry Point (src/index.ts): Validates required environment variables and starts the MCP server
2. Server (src/server.ts): Sets up the MCP server, defines available tools, and routes tool calls to appropriate services
3. Services (src/services/): Core business logic for interacting with YouTube APIs
   • VideoService: Handles video operations (get video details, search videos)
   • TranscriptService: Retrieves and manages video transcripts
   • PlaylistService: Manages playlist operations
   • ChannelService: Handles channel-related operations
4. Types (src/types.ts): TypeScript interfaces for function parameters and data structures
5. Functions (src/functions/): Additional functionality (currently excluded from compilation but available for future extensions)

MCP Tool Registration

Tools are registered in src/server.ts through the ListToolsRequestSchema handler (lines 39-165). Each tool has:

• A name following the pattern {service}_{operation} (e.g., videos_getVideo)
• A description for the AI model
• An input schema defining expected parameters

Tool execution is handled in CallToolRequestSchema handler (lines 167-254) with a switch statement routing to the appropriate service method.