# youtube-mcp

An [MCP](https://modelcontextprotocol.io) server that gives Claude control of a
YouTube channel: upload videos, edit metadata, schedule releases, and read
analytics — through YouTube's official Data and Analytics APIs.

Built for people running a posting workflow, where "publish Tuesday's video at
3pm and tell me how last week's did" should be one sentence, not twenty clicks.

## Read this before you build on it

Two limits are policy, not code. Neither stops you developing, but both will
shape what you can ship, and it's better to know now than after you've wired up
a content pipeline.

**1. Unaudited API projects can only upload private videos.** Until your Google
Cloud project passes YouTube's review, every video the API uploads is locked to
private — you can't publish, and you can't flip it to public afterwards. Fix it
by submitting the [YouTube API Services Audit and Quota Extension form](https://support.google.com/youtube/contact/yt_api_form).
The server tells you when this has happened rather than leaving you to wonder
where your video went.

**2. Quota is 10,000 units/day, and an upload costs ~1,600.** That's about six
uploads a day, then you're locked out until midnight Pacific. Raising it goes
through the same form. Costs per tool are listed below so you can budget.

## Setup

### 1. Google Cloud

1. Create a project at [console.cloud.google.com](https://console.cloud.google.com)
2. Enable **YouTube Data API v3** and **YouTube Analytics API**
3. Configure the OAuth consent screen, adding your channel's Google account as
   a test user
4. Create an **OAuth 2.0 Client ID** of type **Desktop app**, download the JSON

> While the consent screen is in "Testing" status, refresh tokens expire after
> 7 days and you'll re-authorize constantly. Publishing the app stops that.

### 2. Install

```bash
git clone https://github.com/GhOsT0407/youtube-mcp.git
cd youtube-mcp
pip install -e .
```

### 3. Authorize

Save the downloaded JSON to `~/.youtube-mcp/client_secret.json`, then:

```bash
youtube-mcp auth
```

That opens a browser once and stores a refresh token at
`~/.youtube-mcp/token.json`. The server never runs this flow itself — an MCP
tool call has no way to show you a consent screen.

### 4. Add to your MCP client

Claude Code:

```bash
claude mcp add youtube -- youtube-mcp
```

Claude Desktop — in `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "youtube": {
      "command": "youtube-mcp"
    }
  }
}
```

If `youtube-mcp` isn't on PATH, use the full interpreter path and
`["-m", "youtube_mcp"]` as args.

Then ask Claude to run `auth_status` to confirm it's connected.

## Tools

| Tool | What it does | Quota |
|---|---|---|
| `auth_status` | Confirm credentials, show which channel they control | 1 |
| `upload_video` | Upload a file with title, description, tags, privacy, optional schedule | ~1600 |
| `update_video` | Change metadata on an existing video | ~51 |
| `schedule_video` | Set a private video to go public at a given time | ~51 |
| `set_thumbnail` | Set a custom thumbnail | ~50 |
| `list_my_videos` | Recent uploads, newest first — how you find video IDs | ~3 |
| `video_analytics` | Views, watch time, retention for one video | separate quota |
| `channel_analytics` | Channel-wide totals, or a daily/per-video breakdown | separate quota |

### Notes that save debugging time

- **`update_video` merges.** The raw API replaces the entire snippet on write,
  so a partial update silently blanks your description. This reads the current
  state and merges first — passing only `title` changes only the title.
- **Scheduling requires privacy.** YouTube only honours `publishAt` on a
  private video. `schedule_video` and `upload_video` set that for you.
- **`made_for_kids` is a legal declaration** under COPPA, not a preference. Set
  it to match what the content actually is.
- **Analytics lag 2–3 days.** Yesterday's numbers won't be there yet.
- **Large uploads are slow and synchronous.** A long file can outlast an MCP
  client's tool timeout. Upload big files when you can leave it alone.

## Example

> Upload `episode-12.mp4` as "How I Automate My Channel", tag it automation and
> youtube, schedule it for next Tuesday 3pm UTC, then show me how episode 11 did
> over the last 30 days.

Claude chains `upload_video` → `schedule_video` → `list_my_videos` →
`video_analytics` on its own.

## Security

Your `client_secret.json` and `token.json` are the keys to your channel. They
live in `~/.youtube-mcp/`, and `.gitignore` excludes them — keep it that way.
Anyone with that token can post as you.

## Requirements

- Python 3.10+
- A Google Cloud project with the two APIs enabled
- A YouTube channel on the authorizing account

## License

MIT — see [LICENSE](LICENSE).