# YouTube Transcript MCP Server

[![Go Version](https://img.shields.io/github/go-mod/go-version/kyong0612/youtube-mcp)](go.mod)
[![License: MIT](https://img.shields.io/github/license/kyong0612/youtube-mcp)](LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/kyong0612/youtube-mcp/ci.yml?branch=main&label=CI)](https://github.com/kyong0612/youtube-mcp/actions/workflows/ci.yml)

A high-performance Model Context Protocol (MCP) server for fetching YouTube video transcripts, implemented in Go.

## ⚡ Quick Start (Claude Code)

Install the stdio binary, then register it with Claude Code in a single command:

```bash
# 1. Install the stdio binary (requires Go 1.24+)
go install github.com/kyong0612/youtube-mcp/cmd/mcp@latest
mv "$(go env GOPATH)/bin/mcp" "$(go env GOPATH)/bin/youtube-mcp-stdio"

# 2. Register the server with Claude Code (one-liner)
claude mcp add youtube-transcript -- youtube-mcp-stdio
```

For Claude Desktop, Cursor, and manual JSON configuration, see the **MCP Client Setup** section below.

## 🎬 Demo

> **Demo GIF coming soon.** A short screen recording showing transcript fetching from an MCP client will be added here.

## 📦 MCP Registry & Distribution

- **Registries**: This server is being prepared for discovery via MCP registries such as the [MCP Registry](https://github.com/modelcontextprotocol/registry) and [Smithery](https://smithery.ai/). The registry manifest is added in a separate PR.
- **Prebuilt binaries & Docker image**: Cross-platform binaries and a container image will be published after the first GitHub release is tagged. Until then, install via `go install` (above) or build from source (see the **Installation** section below).

## 🚀 Features

- **MCP Protocol 2024-11-05 Compliant**: Full implementation of the Model Context Protocol
- **5 Powerful Tools**:
  - `get_transcript`: Fetch transcript for a single video
  - `get_multiple_transcripts`: Batch process multiple videos
  - `translate_transcript`: Fetch captions in the specified language (including YouTube's auto-translated captions when available). This does not machine-translate arbitrary text.
  - `format_transcript`: Format transcripts (plain text, SRT, VTT, etc.)
  - `list_available_languages`: List available subtitle languages
- **High Performance**: Built with Go for speed and efficiency
- **Caching**: In-memory cache implemented (Redis is planned/not yet implemented; `CACHE_TYPE=redis` currently falls back to the memory cache)
- **Rate Limiting**: Protect against YouTube API limits
- **Proxy Support**: Rotate through multiple proxies
- **Docker Ready**: Easy deployment with Docker Compose
- **Monitoring**: Built-in health checks (Prometheus metrics are planned/not yet implemented)

## 📋 Requirements

- Go 1.24 or higher
- Docker & Docker Compose (optional)
- Internet connection

## 🎯 MCP Client Setup

### Quick Install (Recommended)

Use the automatic installation script:

```bash
# Clone the repository
git clone https://github.com/kyong0612/youtube-mcp.git
cd youtube-mcp

# Run the installer
./scripts/install-mcp.sh
```

The installer will:
- Build the MCP server binary
- Configure Claude Desktop automatically
- Set up environment variables

### Install via Go Install

You can install the MCP server directly using `go install`:

```bash
# Install the stdio version for MCP clients
go install github.com/kyong0612/youtube-mcp/cmd/mcp@latest

# The binary will be installed to $GOPATH/bin/mcp
# Rename it for clarity
mv $GOPATH/bin/mcp $GOPATH/bin/youtube-mcp-stdio

# Or install to a specific location
GOBIN=/usr/local/bin go install github.com/kyong0612/youtube-mcp/cmd/mcp@latest
sudo mv /usr/local/bin/mcp /usr/local/bin/youtube-mcp-stdio
```

Then configure your MCP client to use the installed binary:

```json
{
  "mcpServers": {
    "youtube-transcript": {
      "command": "youtube-mcp-stdio",
      "args": [],
      "env": {
        "LOG_LEVEL": "info",
        "CACHE_ENABLED": "true",
        "YOUTUBE_DEFAULT_LANGUAGES": "en,ja"
      }
    }
  }
}
```

**Note**: If you installed to `$GOPATH/bin`, make sure it's in your PATH, or use the full path in the command field.

### Manual Setup

#### Claude Desktop

To use this server with Claude Desktop, add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "youtube-transcript": {
      "command": "/path/to/youtube-mcp/youtube-mcp-stdio",
      "args": [],
      "env": {
        "LOG_LEVEL": "info",
        "CACHE_ENABLED": "true",
        "YOUTUBE_DEFAULT_LANGUAGES": "en,ja"
      }
    }
  }
}
```

**Important**: Claude Desktop requires the stdio version of the server (`youtube-mcp-stdio`), not the HTTP server.

Build the stdio server:
```bash
go build -o youtube-mcp-stdio ./cmd/mcp/
```

#### Claude Code (claude.ai/code)

Once `youtube-mcp-stdio` is on your `PATH` (see [Install via Go Install](#install-via-go-install)), register it with a single command:

```bash
claude mcp add youtube-transcript -- youtube-mcp-stdio
```

You can also point Claude Code at an explicit binary path and pass environment variables:

```bash
claude mcp add youtube-transcript \
  --env YOUTUBE_DEFAULT_LANGUAGES=en,ja \
  -- /path/to/youtube-mcp/youtube-mcp-stdio
```

#### Cursor

Cursor supports MCP servers through its settings. To configure:

1. Open Cursor Settings (`Cmd+,` on macOS, `Ctrl+,` on Windows/Linux)
2. Search for "MCP" or "Model Context Protocol"
3. Add the server configuration:

```json
{
  "mcp.servers": {
    "youtube-transcript": {
      "command": "/path/to/youtube-mcp/youtube-mcp-stdio",
      "args": [],
      "env": {
        "LOG_LEVEL": "info",
        "CACHE_ENABLED": "true",
        "YOUTUBE_DEFAULT_LANGUAGES": "en,ja"
      }
    }
  }
}
```

See [docs/mcp-client-setup.md](docs/mcp-client-setup.md) for detailed setup instructions.

## 🛠️ Installation

### Using Go

```bash
# Clone the repository
git clone https://github.com/kyong0612/youtube-mcp.git
cd youtube-mcp

# Install dependencies
make deps

# Build the application
make build

# Run the server
make run
```

### Using Docker

```bash
# Clone the repository
git clone https://github.com/kyong0612/youtube-mcp.git
cd youtube-mcp

# Setup environment
make env-setup
# Edit .env file with your configuration

# Start with Docker Compose
make up
```

## ⚙️ Configuration

Copy `.env.example` to `.env` and configure:

```bash
cp .env.example .env
```

Key configuration options:

- `PORT`: Server port (default: 8080)
- `YOUTUBE_DEFAULT_LANGUAGES`: Default languages for transcripts
- `CACHE_TYPE`: Cache type (memory/redis)
- `SECURITY_ENABLE_AUTH`: Enable API authentication
- `LOG_LEVEL`: Logging level (debug/info/warn/error)

## 🔧 Usage

### Using with MCP Clients (Claude Desktop, Cursor, etc.)

The MCP server will be automatically started by your MCP client. Once configured, you can use the tools directly in your conversations.

### Using as HTTP Server

For development or testing, you can also run the HTTP server version:

```bash
# Run HTTP server
make run
```

Then test with:

```bash
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize"
  }'
```

### List Available Tools

```bash
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'
```

### Get Transcript

```bash
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_transcript",
      "arguments": {
        "video_identifier": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "languages": ["en", "ja"],
        "preserve_formatting": false
      }
    }
  }'
```

### Get Multiple Transcripts

```bash
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_multiple_transcripts",
      "arguments": {
        "video_identifiers": ["dQw4w9WgXcQ", "jNQXAC9IVRw"],
        "languages": ["en"],
        "continue_on_error": true
      }
    }
  }'
```

## 🧪 Development

### Running Tests

```bash
# Run all tests
make test

# Run with coverage
make test-coverage

# Run benchmarks
make benchmark
```

### Code Quality

```bash
# Format code
make fmt

# Run linter
make lint

# Security scan
make security
```

### Hot Reload Development

```bash
# Install air for hot reload
go install github.com/air-verse/air@latest

# Run with hot reload
make dev
```

## 🐳 Docker Deployment

### Basic Deployment

```bash
# Build and start
make up-build

# View logs
make logs

# Stop services
make down
```

### With Redis Cache

```bash
# Start with Redis
make up-redis
```

### With Monitoring

```bash
# Start with Prometheus & Grafana
make up-monitoring
```

## 📊 Monitoring

### Health Check

```bash
curl http://localhost:8080/health
```

### Readiness Check

```bash
curl http://localhost:8080/ready
```

### Metrics

> **Note**: Prometheus metrics are planned/not yet implemented. The `/metrics` endpoint currently returns a placeholder (`# TODO: Implement Prometheus metrics`) along with basic request stats.

```bash
curl http://localhost:9090/metrics
```

## 🐛 Troubleshooting

### Common Issues

#### "Empty transcript response" error
- **Cause**: The server is running in HTTP mode instead of stdio mode
- **Solution**: Ensure you're using `youtube-mcp-stdio` binary, not `youtube-transcript-mcp`

#### "Request timed out" error
- **Cause**: Claude Desktop timeout or server not responding
- **Solution**: 
  - Restart Claude Desktop
  - Check server logs: `LOG_LEVEL=debug` in environment
  - Verify network connectivity

#### "Failed to extract player response" in health checks
- **Cause**: YouTube page structure changes or rate limiting
- **Solution**: This is usually temporary. The server will retry automatically.

#### Server not connecting to Claude Desktop
- **Cause**: Incorrect configuration or binary path
- **Solution**:
  1. Verify the binary exists: `ls -la /path/to/youtube-mcp-stdio`
  2. Check Claude Desktop logs: Developer → Open logs
  3. Ensure the config file is valid JSON

### Debug Mode

Enable debug logging to see detailed information:

```json
{
  "mcpServers": {
    "youtube-transcript": {
      "command": "/path/to/youtube-mcp/youtube-mcp-stdio",
      "args": [],
      "env": {
        "LOG_LEVEL": "debug",
        "CACHE_ENABLED": "true",
        "YOUTUBE_DEFAULT_LANGUAGES": "en,ja"
      }
    }
  }
}
```

## 🔒 Security

- **API Key Authentication**: Set `SECURITY_ENABLE_AUTH=true` and configure API keys
- **Rate Limiting**: Configurable per-IP rate limiting
- **IP Whitelisting/Blacklisting**: Control access by IP address
- **CORS**: Configurable CORS policies

## 🤝 Contributing

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

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Inspired by [youtube-transcript-api](https://github.com/jdepoix/youtube-transcript-api)
- Built for the [Model Context Protocol](https://modelcontextprotocol.io/)

## ⚠️ Disclaimer

This tool is for educational and research purposes. Please respect YouTube's Terms of Service and copyright laws when using transcripts.