# YouTube Tools MCP Server - Project Summary
## What Was Built
A complete TypeScript-based MCP (Model Context Protocol) server that provides YouTube transcript extraction functionality.
## Key Components
### 1. Core Server (`src/index.ts`)
- **MCP Server Implementation**: Built using the official `@modelcontextprotocol/sdk`
- **YouTube Transcript Tool**: Implements `get_youtube_transcript` tool
- **Error Handling**: Comprehensive error handling for various YouTube API scenarios
- **Input Flexibility**: Supports multiple YouTube URL formats and video IDs
- **Language Support**: Optional language parameter for transcript extraction
### 2. Tool Functionality
- **Input**: YouTube video ID or URL, optional language code
- **Output**: Formatted transcript with timestamps and metadata
- **Features**:
- Automatic video ID extraction from various URL formats
- Timestamp formatting (MM:SS or H:MM:SS)
- Comprehensive error messages for common issues
- Language-specific transcript fetching
### 3. Project Structure
```
youtube-tools-mcp/
├── src/
│ └── index.ts # Main MCP server implementation
├── build/ # Compiled JavaScript output
├── docs/
│ ├── usage-examples.md # Comprehensive usage guide
│ └── project-summary.md # This file
├── temp/ # Test files and configuration examples
│ ├── test-transcript.js
│ ├── test-mcp-server.js
│ └── claude-desktop-config.json
├── package.json # Project configuration and dependencies
├── tsconfig.json # TypeScript configuration
├── README.md # Main project documentation
└── .gitignore # Git ignore rules
```
## Dependencies
### Production Dependencies
- `@modelcontextprotocol/sdk`: Official MCP SDK for TypeScript
- `youtube-transcript`: Library for extracting YouTube transcripts
### Development Dependencies
- `typescript`: TypeScript compiler
- `@types/node`: Node.js type definitions
## Usage
### 1. Installation
```bash
pnpm install
pnpm run build
```
### 2. Configuration
Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"youtube-tools": {
"command": "node",
"args": ["/absolute/path/to/youtube-tools-mcp/build/index.js"]
}
}
}
```
### 3. Usage in Claude
- "Get the transcript for this YouTube video: [URL]"
- "Extract transcript from video ID: [ID]"
- "Get the Spanish transcript for: [URL]"
## Technical Implementation Details
### MCP Protocol Compliance
- Implements required MCP server interfaces
- Provides proper tool definitions with JSON schema
- Handles MCP error codes appropriately
- Uses stdio transport for communication
### Error Handling
- **Transcript Disabled**: When video creator disables transcripts
- **No Transcript Found**: When transcript unavailable in requested language
- **Video Unavailable**: For private, deleted, or restricted videos
- **Invalid Parameters**: For malformed video IDs or URLs
### URL Processing
Supports multiple YouTube URL formats:
- `https://www.youtube.com/watch?v=VIDEO_ID`
- `https://youtu.be/VIDEO_ID`
- `https://www.youtube.com/embed/VIDEO_ID`
- `VIDEO_ID` (direct video ID)
### Output Format
```
YouTube Transcript for Video ID: [ID]
Language: [LANG]
Total Segments: [COUNT]
Duration: [TIME]
--- TRANSCRIPT ---
[0:00] First transcript segment
[0:15] Second transcript segment
...
```
## Testing
### Available Test Scripts
- `pnpm run test`: Test YouTube transcript library directly
- `pnpm run test-mcp`: Test MCP server functionality
- `pnpm start`: Run the server (for manual testing)
## Limitations and Considerations
1. **YouTube API Dependency**: Uses unofficial YouTube API via `youtube-transcript` library
2. **Transcript Availability**: Not all videos have transcripts available
3. **Language Support**: Limited to languages provided by YouTube's automatic transcription
4. **Rate Limiting**: May be subject to YouTube's rate limiting policies
## Future Enhancements
Potential improvements could include:
- Additional YouTube tools (video metadata, comments, etc.)
- Transcript summarization capabilities
- Support for playlist processing
- Caching mechanisms for frequently requested transcripts
- Integration with official YouTube Data API for enhanced metadata
## Success Criteria Met
✅ **TypeScript MCP Server**: Complete implementation using official SDK
✅ **YouTube Transcript Tool**: Functional tool that accepts video ID and returns transcript
✅ **Error Handling**: Comprehensive error handling for various scenarios
✅ **Documentation**: Complete usage examples and setup instructions
✅ **Project Structure**: Clean, organized codebase following best practices
✅ **Package Management**: Uses pnpm as requested
✅ **Modular Design**: Separate files for different concerns
