# YouTube MCP

Local, read-only MCP server for YouTube Data API v3 and YouTube Analytics API.

Guides:

- English: [docs/en.md](docs/en.md)
- 中文教程：[docs/zh-cn.md](docs/zh-cn.md)

## Features

- Public YouTube Data API lookups with an API key.
- OAuth-based private channel reads for the authenticated user's own channel.
- YouTube Analytics reports for videos and channels.
- Local stdio MCP transport with no hosted service.

## Security model

- Runs locally over stdio.
- Uses only read scopes:
  - `https://www.googleapis.com/auth/youtube.readonly`
  - `https://www.googleapis.com/auth/yt-analytics.readonly`
- Keeps Google API keys, OAuth client files, and OAuth tokens out of Git.
- Looks for credentials in `~/.config/youtube-mcp/` by default.

Never commit these files:

- `~/.config/youtube-mcp/api_key.txt`
- `~/.config/youtube-mcp/client_secret.json`
- `~/.config/youtube-mcp/token.json`

## Google setup

1. Create a Google Cloud project.
2. Enable YouTube Data API v3 and YouTube Analytics API.
3. Create an OAuth 2.0 Client ID with application type `Desktop app`.
4. Download the client JSON.
5. Save it as:

```bash
mkdir -p ~/.config/youtube-mcp
cp ~/Downloads/client_secret_*.json ~/.config/youtube-mcp/client_secret.json
chmod 600 ~/.config/youtube-mcp/client_secret.json
```

## API key

For public YouTube Data API v3 calls, save the API key here:

```bash
mkdir -p ~/.config/youtube-mcp
printf '%s\n' 'YOUR_YOUTUBE_DATA_API_KEY' > ~/.config/youtube-mcp/api_key.txt
chmod 600 ~/.config/youtube-mcp/api_key.txt
```

The API key is used by:

- `youtube_search_videos`
- `youtube_get_video`
- `youtube_get_channel`

OAuth is still required for private or account-scoped tools:

- `youtube_list_my_videos`
- `youtube_get_video_analytics`
- `youtube_get_channel_analytics`

## Run locally

From this directory:

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
PYTHONPATH=src python3 -m youtube_mcp.server
```

Example MCP config:

```json
{
  "mcpServers": {
    "youtube": {
      "command": "python3",
      "args": ["-m", "youtube_mcp.server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/youtube-mcp/src"
      }
    }
  }
}
```

## OAuth note

`youtube_auth_url` returns the Google authorization URL. Open it, approve the read-only scopes, copy the authorization `code`, then call `youtube_auth_exchange_code` with that code. The token is saved at:

```text
~/.config/youtube-mcp/token.json
```

## Tools

- `youtube_auth_status`
- `youtube_auth_url`
- `youtube_auth_exchange_code`
- `youtube_search_videos`
- `youtube_get_video`
- `youtube_get_channel`
- `youtube_list_my_videos`
- `youtube_get_video_analytics`
- `youtube_get_channel_analytics`

## Development

Run the tests with:

```bash
PYTHONPATH=src python3 -m unittest discover -s tests
```

## License

MIT