YouTube Content Automation

A local AI-powered YouTube content management system. Claude Code acts as the AI brain; an MCP server handles all data operations against Google Sheets, Docs, Drive, and web research APIs.

You (conversation) → Claude Code (AI reasoning) → MCP Tools (data layer) → Google APIs

Prerequisites

• Python 3.10+

• Claude Code CLI installed

• A Google Cloud project with the Sheets, Docs, and Drive APIs enabled

• A Google Sheet to use as your content database

Installation

git clone <repo-url>
cd youtube-mcp

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

pip install -r requirements.txt
pip install -e .                   # installs the `content` CLI command

Google Cloud Setup

1. Go to Google Cloud Console and create or select a project.

2. Enable these APIs: Google Sheets API, Google Docs API, Google Drive API.

3. Under APIs & Services → Credentials, create an OAuth 2.0 Client ID (Desktop app type).

4. Download the JSON file and save it as client_secret.json in the project root.

Environment Configuration

cp .env.example .env

Open .env and fill in:

One-Time Google Auth

Run the OAuth flow once to generate a refresh token:

python -m commands.cli auth client_secret.json

A browser window will open asking you to sign in. After approval, the terminal prints your GOOGLE_REFRESH_TOKEN — copy it into .env. The token is also cached locally in config/token.json and auto-refreshed on subsequent runs.

Initial Sheet & Drive Setup

python -m commands.cli setup

This creates the column headers in your Google Sheet and the Drive subfolder structure (Research, Scripts, Thumbnails, Assets, Published) under your GOOGLE_DRIVE_FOLDER.

Registering the MCP Server with Claude Code

Open .mcp.json (project root) and update the paths to match your environment:

{
  "mcpServers": {
    "youtube-content": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "mcpserver.server"],
      "cwd": "/absolute/path/to/youtube-mcp",
      "env": {
        "PYTHONPATH": "/absolute/path/to/youtube-mcp"
      }
    }
  }
}

Claude Code auto-discovers .mcp.json when you open the project directory. Alternatively register it manually:

claude mcp add youtube-content /path/to/.venv/bin/python -- -m mcpserver.server

Restart Claude Code and confirm the server appears under /mcp.

Using the System

Once the MCP server is connected, talk to Claude Code naturally:

CLI Commands

You can also drive the system from the terminal without Claude Code:

content setup                              # initialize sheet and Drive
content list                               # list all videos
content list --status "Research Complete"  # filter by status
content schedule                           # show publishing calendar
content pending                            # pipeline snapshot
content stats                              # counts by status
content research --topic "Property Tax"    # build a research brief
content script --row 14                    # load script context
content visuals --row 14                   # load visual context

Customizing Prompts

All AI prompt templates are plain Markdown files in prompts/. Edit them to change tone, structure, or guidelines without touching any code:

Google Sheet Schema

Sheet name: Videos

Status flow: Idea → Researching → Research Complete → Script Writing → Script Complete → Thumbnail Ready → Scheduled → Published → Archived

Project Structure

youtube-mcp/
├── mcpserver/        # MCP server (tools Claude Code calls)
├── services/         # Google API clients (Sheets, Docs, Drive, Auth)
├── agents/           # Agent logic (research, script, visual, analytics)
├── commands/         # CLI entry points
├── config/           # Settings and cached OAuth token
├── prompts/          # Editable AI prompt templates
├── logs/             # Rotating daily log files
├── cache/            # Research cache (TTL configurable in .env)
├── .mcp.json         # MCP server config for Claude Code
├── .env.example      # Environment variable template
└── requirements.txt  # Python dependencies

Troubleshooting

MCP server not connecting — check that the command path in .mcp.json points to the Python binary inside your .venv, and that cwd is the absolute project path.

Google auth errors — delete config/token.json and re-run python -m commands.cli auth client_secret.json.

"No valid Google credentials" — make sure GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_REFRESH_TOKEN are all set in .env.

Web search returning no results — the system falls back to DuckDuckGo when BRAVE_SEARCH_API_KEY is unset, but Brave gives better results.