npm package: @htekdev/youtube-mcp-server
Description: MCP server providing full YouTube Data API v3 search and retrieval capabilities for AI agents
Author: htekdev
Latest version: 1.1.2

# YouTube MCP Server

A Model Context Protocol (MCP) server providing full YouTube Data API v3 search and retrieval capabilities for AI agents.

## Installation

```bash
npm install @htekdev/youtube-mcp-server
```

Or run directly with npx:

```bash
npx @htekdev/youtube-mcp-server
```

## Configuration

### For Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "youtube": {
      "command": "npx",
      "args": ["@htekdev/youtube-mcp-server"],
      "env": {
        "YOUTUBE_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### For Other MCP Clients

Run the server directly:

```bash
YOUTUBE_API_KEY=your_api_key npx @htekdev/youtube-mcp-server
```

### Getting an API Key

1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
2. Create a new project or select existing
3. Enable the YouTube Data API v3
4. Create an API key credential

You can also configure the API key at runtime using the `setup_youtube` tool.

## Available Tools

### Setup & Status
| Tool | Description |
|------|-------------|
| `setup_youtube` | Configure API key and defaults |
| `youtube_status` | Check configuration status |

### Search
| Tool | Description |
|------|-------------|
| `youtube_search` | Full-featured search with all filters |
| `youtube_search_videos` | Simplified video search |
| `youtube_search_related` | Find videos related to a specific video |

### Videos
| Tool | Description |
|------|-------------|
| `youtube_video_details` | Get comprehensive video information |
| `youtube_video_list` | Batch retrieve multiple videos |
| `youtube_trending` | Get trending/popular videos |

### Channels
| Tool | Description |
|------|-------------|
| `youtube_channel_details` | Get channel info (by ID, handle, or username) |
| `youtube_channel_videos` | List videos from a channel |
| `youtube_channel_search` | Search within a specific channel |

### Playlists
| Tool | Description |
|------|-------------|
| `youtube_playlist_details` | Get playlist information |
| `youtube_playlist_items` | List all videos in a playlist |
| `youtube_playlists_by_channel` | Get all playlists from a channel |

### Comments
| Tool | Description |
|------|-------------|
| `youtube_comment_threads` | Get top-level comments on a video |
| `youtube_comment_replies` | Get replies to a specific comment |

### Other
| Tool | Description |
|------|-------------|
| `youtube_captions_list` | List available captions/subtitles |
| `youtube_live_broadcasts` | Search for live streams |

## Usage Examples

### Search for Videos

```json
{
  "tool": "youtube_search",
  "args": {
    "q": "machine learning tutorial",
    "type": "video",
    "maxResults": 10,
    "order": "viewCount",
    "videoDuration": "medium"
  }
}
```

### Get Video Details

```json
{
  "tool": "youtube_video_details",
  "args": {
    "videoId": "dQw4w9WgXcQ",
    "parts": ["snippet", "statistics", "contentDetails"]
  }
}
```

### Get Channel by Handle

```json
{
  "tool": "youtube_channel_details",
  "args": {
    "handle": "@MrBeast"
  }
}
```

### Search Live Streams

```json
{
  "tool": "youtube_live_broadcasts",
  "args": {
    "q": "gaming",
    "eventType": "live",
    "maxResults": 10
  }
}
```

## Development

### Prerequisites

- Node.js >= 18.0.0
- npm

### Setup

```bash
npm install
```

### Running Tests

```bash
npm test              # Run tests once
npm run test:watch    # Watch mode
npm run test:coverage # With coverage report
```

### Type Checking

```bash
npm run typecheck
```

### Building

```bash
npm run bundle
```

## API Quota Notes

YouTube Data API has quota limits (default 10,000 units/day). Tool quota costs:

| Operation | Cost |
|-----------|------|
| Search | 100 units |
| Videos list | 1 unit |
| Channels list | 1 unit |
| Playlists list | 1 unit |
| PlaylistItems list | 1 unit |
| CommentThreads list | 1 unit |
| Comments list | 1 unit |
| Captions list | 50 units |

## License

MIT

## Author

[htekdev](https://github.com/htekdev)