tubekit-mcp

Compliance-aware Model Context Protocol server for YouTube publishing, analytics, and creator insights — every action gated, metered, and audited before it touches a channel.

tubekit-mcp is an MCP server: you connect it to an MCP client (Claude Desktop, Claude Code, …) and the assistant can then publish and manage videos on a YouTube channel on your behalf, with compliance checks, quota accounting, idempotent uploads and a tamper-evident audit log on every state-changing call. Licensed under FSL-1.1-MIT — run and self-host it freely, commercially or not; each release becomes plain MIT two years after publication.

Architecture

A single tool call (e.g. upload_video) flows through a compliance gate, a quota / idempotency ledger, an OAuth refresh, the YouTube API, and a tamper-evident audit row — with the pure core kept free of protocol concerns, a boundary enforced in CI by an AST fitness test (tests/unit/services/test_no_fastmcp_imports.py).

flowchart LR
    client["MCP client<br/>(Claude Desktop / Code)"]
    subgraph edge["Protocol edge"]
      transport["Transport<br/>stdio · HTTP + Bearer"]
      tool["Tool wrapper"]
    end
    subgraph core["Pure core — no protocol imports (CI-enforced)"]
      compliance{"Compliance<br/>gate"}
      ledger["Quota +<br/>idempotency<br/>ledger"]
      oauth["OAuth refresh<br/>(Fernet at rest)"]
    end
    upstream["YouTube<br/>Data / Analytics API"]
    audit[("Tamper-evident<br/>hash-chained<br/>audit log")]

    client --> transport --> tool --> compliance
    compliance -->|pass| ledger --> oauth --> upstream
    compliance -->|fail| suggestion["Suggestion →<br/>agent retries"]
    tool -. audited .-> audit
    ledger -. audited .-> audit
    oauth -. audited .-> audit

Why this exists. Agents are starting to operate real YouTube channels — and a channel is an asset you can lose. One bad call can publish a video that violates policy, burn the day's API quota (an upload costs 1600 of the default 10,000 daily units), or double-publish on a retry. Generic YouTube wrappers hand the agent the raw API; tubekit wraps every call in the guardrails an unattended operator needs: a compliance gate before anything goes live, quota accounted before it is spent, idempotent retries, OAuth tokens encrypted at rest (fingerprint-only logging), and a tamper-evident audit chain of everything the agent did. Full design rationale in ADR 0001.

Usage

Prerequisites

Before an assistant can act on a channel you need, once per channel:

1. A Google Cloud project with the YouTube Data API v3 (and YouTube Analytics API if you use get_analytics) enabled.
2. An OAuth client of type Desktop app, downloaded as client_secret.json.
3. The channel whose Google account will grant the consent.

The OAuth grant is interactive and only happens here — tubekit stores the resulting refresh token Fernet-encrypted and never prints it. Never used Google Cloud Console? docs/runbooks/gcp-setup.md walks the whole thing from zero (project, APIs, consent screen, client type, and the two Google policies — token expiry in testing, private-locked uploads for unaudited projects — that surprise people later). The consent flows themselves are in docs/runbooks/oauth-bootstrap.md.

Install

From PyPI:

uv tool install tubekit-mcp   # installs the tubekit / tubekit-mcp-* commands

Use uv tool install, not uvx, for a real setup: the one-time steps below need the tubekit CLI to still be there afterwards. uvx tubekit-mcp runs the stdio server from a throwaway environment, which is what an MCP client's config points at once the setup is done.

The server will not start yet, and that is deliberate — it refuses to run without a master key rather than inventing one, since that key is what encrypts your OAuth tokens at rest. One-time setup below is the two commands that fix it.

Or from source, for development:

git clone https://github.com/santiriera626/tubekit-mcp.git tubekit-mcp && cd tubekit-mcp
uv sync --all-extras        # installs the tubekit / tubekit-mcp-* entry points
make db-upgrade             # builds the state schema (wraps `tubekit db upgrade`;
                            #   `tubekit db current` prints the applied revision)

(uv itself installs with curl -LsSf https://astral.sh/uv/install.sh | sh.)

Try it in 60 seconds — no Google account needed

The compliance engine is pure-local, so you can watch the gate and its self-correction Suggestions work before touching Google Cloud:

cat > video.json <<'EOF'
{
  "title": "Test Upload — Compliance Gate Demo",
  "description": "Demo description for the compliance gate.",
  "tags": ["demo", "test"],
  "ai_disclosure": false,
  "made_for_kids": null,
  "category_id": "10"
}
EOF
uv run tubekit compliance test video.json

Compliance: PASSED  (8 rules evaluated)
  WARNING AI_DISCLOSURE_MISSING: AI disclosure flag is false; confirm this is the
      channel owner's intended policy for AI-generated content.
      suggestion: action=set field=metadata.ai_disclosure value=True
  WARNING KIDS_FLAG_NOT_SET: made_for_kids is unset; set it explicitly to true or
      false (this rule does not classify by content).
      suggestion: action=set field=metadata.made_for_kids value=False

An error-severity violation — say a 126-character title — fails the gate with exit 1 and a machine-applicable fix (suggestion: action=truncate field=metadata.title value=100). That is the same Suggestion an agent receives from a rejected upload_video and applies before retrying (ADR D8). tubekit compliance list prints the rule catalog; tubekit compliance manifest exports it for external auditors.

Install with an AI agent

Rather not type the commands above yourself? Paste the block below into Claude Code (or any coding agent with shell access) and it will clone, install and register the server for you. It stops at the boundary above: no Google account, client_secret.json or OAuth consent is involved.

Install tubekit-mcp and register it as an MCP server. Stop and report if any step fails.

1. Clone the repo and enter it (install uv first if missing:
   curl -LsSf https://astral.sh/uv/install.sh | sh):
   git clone https://github.com/santiriera626/tubekit-mcp.git tubekit-mcp && cd tubekit-mcp

2. Install dependencies, apply the database migrations and create the Fernet
   master key (the server refuses to start without one):
   uv sync --all-extras
   make db-upgrade
   uv run tubekit auth init-master-key
   (Idempotent: an existing key is reported and left untouched.)

3. Run the zero-credential compliance smoke check to confirm the install works:
   cat > video.json <<'EOF'
   {
     "title": "Test Upload — Compliance Gate Demo",
     "description": "Demo description for the compliance gate.",
     "tags": ["demo", "test"],
     "ai_disclosure": false,
     "made_for_kids": null,
     "category_id": "10"
   }
   EOF
   uv run tubekit compliance test video.json
   Expect "Compliance: PASSED (8 rules evaluated)" and exit code 0.

4. Register the server with Claude Code over stdio, using absolute paths:
   claude mcp add tubekit \
     -e TUBEKIT_STATE_DB_PATH="$(pwd)/state.db" \
     -e TUBEKIT_MASTER_KEY_PATH="$HOME/.config/tubekit/master.key" \
     -- "$(pwd)/.venv/bin/tubekit-mcp-stdio"

Do not run `tubekit auth setup-channel` or open any Google consent screen —
OAuth channel bootstrap is a separate, human-in-the-loop step documented in
docs/runbooks/oauth-bootstrap.md. Stop after step 4 and tell me to run that
myself.

Restart your MCP client after registration; it can now call tubekit.health() and list the full tool catalog. Every tool that takes a channel argument — validate_compliance included — needs a configured channel, which means completing One-time setup — including the OAuth consent in docs/runbooks/oauth-bootstrap.md — yourself. The compliance gate itself is testable without any channel via step 3's tubekit compliance test.

One-time setup

# 1. Create the Fernet master key used to encrypt stored tokens (mode 0600).
#    Skip if the agent install above already created it.
tubekit auth init-master-key

# 2. Bootstrap a channel — opens a browser for the OAuth consent.
#    The alias is positional; --channel-id, --gcp-project, --client-secrets
#    and --scopes are all required (see docs/runbooks/oauth-bootstrap.md).
tubekit auth setup-channel mychannel \
  --channel-id UCxxxxxxxxxxxxxxxxxxxxxx \
  --gcp-project my-gcp-project \
  --client-secrets ./client_secret.json \
  --scopes youtube.upload,youtube.readonly