# ytmcp

> **Unofficial YouTube API + MCP server** — let AI agents control a YouTube channel end-to-end.

[![CI](https://github.com/Lightforce325/ytmcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Lightforce325/ytmcp/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-compatible-purple)](https://modelcontextprotocol.io)

`ytmcp` is a Python library, REST API, CLI, and **[Model Context Protocol](https://modelcontextprotocol.io)** server that wraps an *unofficial* YouTube client. It lets AI agents (Claude Desktop, Cursor, custom agents…) upload videos, edit metadata, manage playlists, moderate comments, and read analytics — all through MCP tools.

---

## ⚠️ Disclaimer

This project is provided **for educational and research purposes only**.

- It uses **reverse-engineered, undocumented** YouTube endpoints that may change or break at any time.
- Automating YouTube may **violate YouTube's Terms of Service**.
- Using this software **can result in account suspension or termination**.
- The authors accept **no liability** for any consequences arising from its use.

**Use at your own risk, ideally with a test account.** You are solely responsible for complying with all applicable terms and laws.

---

## ✨ Features

| Domain | Capabilities |
|--------|-------------|
| **Video** | upload (resumable), update metadata, set visibility, set thumbnail, delete, get info |
| **Playlist** | create, list, add/remove videos, delete |
| **Comments** | list, reply, moderate (approve/hold/reject) |
| **Channel** | get info, subscriber count, update branding/links |
| **Analytics** | views, watch-time, subscriber growth, top videos |
| **Search** | search videos, list channel uploads |

Three interfaces share one core:

1. 🐍 **Python library** — `from ytmcp.core import YouTubeClient`
2. 🤖 **MCP server** — `ytmcp serve` (stdio / HTTP)
3. 🌐 **REST API** — `ytmcp api` (FastAPI, auto docs at `/docs`)

---

## 🔐 Authentication (hybrid)

`ytmcp` supports **two** auth methods and picks automatically (`auth_mode = auto`):

### Option A — Browser cookies (fastest)

1. Export cookies for `youtube.com` with a browser extension (e.g. *Get cookies.txt*) or `yt-dlp --cookies-from-browser chrome --cookies cookies.txt`.
2. Point ytmcp at the file:

```bash
export YTMCP_AUTH_MODE=cookie
export YTMCP_COOKIE_FILE=/path/to/cookies.txt
uv run ytmcp auth verify-cookies /path/to/cookies.txt
```

Supports **Netscape** `cookies.txt` and **JSON** exports (including Playwright `storage_state`).

### Option B — OAuth 2.0 (device flow)

1. Create an OAuth client (type **TVs and Limited Input devices**) in [Google Cloud Console](https://console.cloud.google.com/).
2. Configure and log in:

```bash
export YTMCP_AUTH_MODE=oauth
export YTMCP_OAUTH_CLIENT_ID=...
export YTMCP_OAUTH_CLIENT_SECRET=...
uv run ytmcp auth login
```

Tokens are cached in `~/.ytmcp/oauth_token.json` and refreshed automatically.

Check status any time:

```bash
uv run ytmcp auth status
```

---

## 🚀 Quick start

```bash
# 1. Install
git clone https://github.com/Lightforce325/ytmcp.git
cd ytmcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

# 2. Configure auth (see above)
cp .env.example .env  # then edit

# 3. Run the MCP server
uv run ytmcp serve

# or the REST API
uv run ytmcp api     # http://127.0.0.1:8765/docs
```

---

## 🤖 Connect to Claude Desktop (MCP)

Add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ytmcp": {
      "command": "uv",
      "args": [
        "--directory", "/ABSOLUTE/PATH/TO/ytmcp",
        "run", "ytmcp", "serve"
      ],
      "env": {
        "YTMCP_AUTH_MODE": "cookie",
        "YTMCP_COOKIE_FILE": "/ABSOLUTE/PATH/TO/cookies.txt"
      }
    }
  }
}
```

Restart Claude Desktop — the agent will now see **20 tools** for controlling your channel.

See [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json) and [`docs/TOOLS.md`](docs/TOOLS.md).

---

## 🧰 MCP tools

| Tool | Auth | Description |
|------|:----:|-------------|
| `upload_video` | ✅ | Upload a video file with metadata |
| `update_video_metadata` | ✅ | Edit title/description/tags/category |
| `set_video_visibility` | ✅ | public / unlisted / private / scheduled |
| `delete_video` | ✅ | Permanently delete a video |
| `get_video_info` | — | Fetch video details |
| `search_videos` | — | Search YouTube |
| `list_channel_videos` | — | List a channel's uploads |
| `create_playlist` | ✅ | Create a playlist |
| `list_playlists` | — | List channel playlists |
| `add_video_to_playlist` | ✅ | Add a video to a playlist |
| `remove_video_from_playlist` | ✅ | Remove a video from a playlist |
| `delete_playlist` | ✅ | Delete a playlist |
| `list_comments` | — | List video comments |
| `reply_to_comment` | ✅ | Reply to a comment |
| `moderate_comment` | ✅ | Approve / hold / reject a comment |
| `get_channel_info` | — | Channel metadata |
| `get_subscriber_count` | — | Subscriber count |
| `update_channel_branding` | ✅ | Banner / avatar / links |
| `get_analytics` | ✅ | Views, watch-time, growth |
| `get_top_videos` | — | Most-viewed videos |

---

## 🧩 Example agent workflow

> "Upload `intro.mp4` as a private video titled *Hello World*, add it to my *Demos* playlist, then reply to the latest comment."

The agent chains: `upload_video` → `list_playlists` → `add_video_to_playlist` → `list_comments` → `reply_to_comment`. See [`examples/agent_batch_upload.py`](examples/agent_batch_upload.py).

---

## 🏗️ Architecture

```
AI Agent ──MCP──► mcp/server.py ──► core/* ──► YouTube endpoints
                     api/app.py  ──►
                     cli.py      ──►
```

See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the full breakdown.

---

## 🧪 Development

```bash
uv pip install -e ".[dev]"
uv run pytest                 # run tests
uv run ruff check .           # lint
uv run ruff format .          # format
uv run mypy src               # type-check
```

---

## 📄 License

[MIT](LICENSE) — provided as-is, without warranty. See the disclaimer above.