# YouTube MCP

This project provides a Python MCP server for a practical YouTube upload and management workflow that uses the real YouTube Data API v3 and YouTube Analytics API with Google OAuth 2.0.

## Architecture

The code is intentionally split into separate layers:

- `youtube_mcp/server.py` exposes MCP tools to Claude or any MCP client.
- `youtube_mcp/services/youtube_service.py` contains the actual YouTube API logic and validation.
- `youtube_mcp/config.py` reads environment variables and keeps secret values out of source control.

This separation keeps the tool layer focused on MCP contracts while the service layer handles YouTube API requests, validation, and error handling.

## Required OAuth and API approach

This project is designed for authenticated workflow operations, not API-key-only use.

For upload, channel management, thumbnail update, and other private/channel-based actions, use Google OAuth 2.0 with the following scopes:

- `https://www.googleapis.com/auth/youtube.upload`
- `https://www.googleapis.com/auth/youtube.readonly`
- `https://www.googleapis.com/auth/youtubepartner`
- `https://www.googleapis.com/auth/yt-analytics.readonly`

The server expects these values in environment variables or a local `.env` file:

```bash
export GOOGLE_CLIENT_ID="your-google-client-id"
export GOOGLE_CLIENT_SECRET="your-google-client-secret"
export YOUTUBE_REFRESH_TOKEN="your-google-refresh-token"
export YOUTUBE_ACCESS_TOKEN="optional-current-access-token"
export YOUTUBE_CHANNEL_ID="optional-channel-id"
```

Never put client secrets, refresh tokens, or access tokens in source code or Git.

## Tool set

### `hello_youtube`
Simple validation tool that returns:

```text
YouTube MCP is working
```

### `upload_video`
Uploads a video file to YouTube.

Inputs:
- `title` (required)
- `description` (required)
- `file_path` (required local/publicly accessible path)
- `tags` (optional list of YouTube tag strings)
- `hashtags` (optional list of hashtags; these are added to the description text)
- `privacy_status` (optional: `public`, `private`, or `unlisted`)
- `scheduled_publish_at` (optional ISO 8601 future datetime; requires `privacy_status="private"` for YouTube scheduling)
- `category_id` (optional)
- `made_for_kids` (optional boolean)

Behavior:
- Does not fake a success result.
- Returns the uploaded video ID only when the YouTube API confirms it.
- Validates `scheduled_publish_at` and rejects non-future or invalid timestamps.
- Treats hashtags separately from YouTube tags; hashtags are represented in the title/description text, while tags go into the video `tags` field.

### `update_video`
Updates video metadata.

Inputs:
- `video_id` (required)
- `title` (optional)
- `description` (optional)
- `tags` (optional)
- `hashtags` (optional)
- `privacy_status` (optional)
- `scheduled_publish_at` (optional)
- `category_id` (optional)
- `made_for_kids` (optional)

Rules:
- Requires a valid update payload.
- For scheduled publishing, YouTube requires private + publishAt workflow.
- Returns the API result only when the update request succeeds.

### `set_thumbnail`
Sets a thumbnail image for an existing YouTube video.

Inputs:
- `video_id` (required)
- `thumbnail_path` (required local file path)

### `get_video_stats`
Gets public YouTube video metadata and statistics for a given video ID.

### `get_channel_info`
Fetches channel metadata for a channel ID, username, or `mine=True` when authenticated.

### `get_latest_videos`
Lists recent videos for a channel.

### `get_video_analytics`
Uses the YouTube Analytics API with authorized metrics for available reporting dimensions and filters.

## Validation and error handling

The service layer validates:
- `privacy_status`
- `scheduled_publish_at`
- missing required parameters
- file existence for uploads and thumbnails
- OAuth environment configuration before channel or upload actions run

If the YouTube API responds with an error, the code raises a clear `RuntimeError` or `ValueError` with the API response details instead of masking the failure.

## Local development / stdio mode

Run the local MCP server over stdio:

```bash
cd /workspaces/youtube-mcp
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m youtube_mcp.server
```

This uses the local stdio transport for testing and debugging.

## Remote HTTP MCP mode for Claude Custom Connector

The repository also supports a remote HTTP transport using the installed official MCP Python SDK.

Set the host/port and transport mode before starting the server:

```bash
cd /workspaces/youtube-mcp
source .venv/bin/activate
export YOUTUBE_MCP_TRANSPORT="http"
export YOUTUBE_MCP_HOST="127.0.0.1"
export YOUTUBE_MCP_PORT="8000"
export YOUTUBE_MCP_HTTP_PATH="/mcp"
python -m youtube_mcp.server
```

This exposes the MCP protocol at:

```text
http://127.0.0.1:8000/mcp
```

The health endpoint is available at:

```text
http://127.0.0.1:8000/health
```

You can verify the health endpoint with:

```bash
curl http://127.0.0.1:8000/health
```

Expected response:

```json
{"status":"ok","service":"youtube-mcp","transport":"http"}
```

## Notes

- `.env` is included in `.gitignore`.
- OAuth tokens and credentials are intentionally kept in environment variables.
- No fake API responses are used.
- No deployment or public publishing is configured in this repository.
- The Google OAuth redirect URI is not changed here.