ytmcp

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

ytmcp is a Python library, REST API, CLI, and Model Context Protocol 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.

Related MCP server: youtube-live-mcp

✨ Features

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:

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.

2. Configure and log in:

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:

uv run ytmcp auth status

🚀 Quick start

# 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:

{
  "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 and docs/TOOLS.md.

🧰 MCP tools

🧩 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.

🏗️ Architecture

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

See docs/ARCHITECTURE.md for the full breakdown.

🧪 Development

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 — provided as-is, without warranty. See the disclaimer above.