YouTube Shorts Agent

io.github.davidmosiahPublished by GitHub account davidmosiahv0.1.6Updated Oct 24, 2026

Agent-first YouTube Shorts uploader: dry-run validation, OAuth checks, synthetic-media metadata.

VerifiedSTDIODesktop onlyProductivity & WorkflowMedia & Design

Overview

AI-generated overview

A local MCP server that lets an assistant prepare, validate and, with OAuth configured, upload YouTube Shorts through the official YouTube Data API.

What you can do
Check OAuth and dry-run readiness and get install guidance for MCP clients, without exposing token values (manifest, connection status). Audit upload scope, synthetic-media flags and local file boundaries. Generate a PKCE authorization URL with local session storage. Upload a Short in dry-run or live mode, with synthetic-media metadata set by default. List recent channel videos for lightweight post-upload verification.
When to use it
Use it when an assistant should prepare and validate Shorts uploads, including title, caption, tags and synthetic-media metadata, before anything is published, or when it should publish through the official API instead of the YouTube Studio interface. Dry-run mode makes it safe to try without credentials.
Requirements
Runs locally over stdio as an npm package (Node.js); an optional loopback-only HTTP mode exists. Live uploads need a Google OAuth client and tokens: YOUTUBE_CLIENT_ID, YOUTUBE_CLIENT_SECRET, plus access and refresh tokens configured in a local .env file. Network access to the YouTube Data API is needed for live calls; dry-run needs no credentials.
Before you install
Live uploads publish content publicly to a YouTube channel and require setting YOUTUBE_DRY_RUN=false; dry-run is the default. YOUTUBE_CLIENT_SECRET and OAuth tokens are sensitive and should stay local and out of Git, and the README advises never printing token values. PKCE session data is stored locally in .agent-data/. Uploads are marked as containing synthetic media by default.

Installation

In SourceWeft

  1. Open YouTube Shorts Agent in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

YouTube Shorts Agent

Agent-first YouTube Shorts uploader for the YouTube Data API.
Dry-run safe, OAuth readiness checks, MCP-ready for Codex / Claude / Cursor / Hermes.

[npm version] [npm downloads] [License MIT] [Built for MCP]

[GitHub stars] [CI status] [Part of the Delx agent stack] [Category]

⭐ If this agent-first tool helps your workflow, please star the repo. Stars make this tooling easier for other builders to discover and help Delx keep shipping open infrastructure.
🧱 Part of the Delx agent stack — 15 open-source MCP servers across body, reach and coordination.

Agent-first YouTube Shorts uploader for the YouTube Data API. It is designed for Codex, Claude, Cursor, Hermes, OpenClaw and any MCP client that needs a predictable upload workflow with dry-run safety, OAuth readiness checks and structured output.

Use it when an agent needs to prepare, validate or upload Shorts through the official API without touching YouTube Studio UI.

What Agents Get

  • youtube_agent_manifest for install/runtime guidance
  • youtube_connection_status before upload attempts
  • youtube_privacy_audit for local token and media boundaries
  • youtube_oauth_authorize_url with local PKCE session storage
  • youtube_upload_short with containsSyntheticMedia support
  • youtube_list_recent_videos for lightweight post-upload checks

Install

bash
npm install -g youtube-shorts-agent

Or run directly:

bash
npm exec --yes --package=youtube-shorts-agent -- youtube-shorts-agent doctor

CLI

bash
youtube-shorts-agent manifest --client codexyoutube-shorts-agent doctoryoutube-shorts-agent privacy-audityoutube-shorts-agent auth-url --redirect-uri http://localhost:8787/callbackyoutube-shorts-agent upload-short --video ./short.mp4 --title "Launch title" --caption-file copy.txtyoutube-shorts-agent list-recent --max-results 10

Dry-run is enabled by default. Set YOUTUBE_DRY_RUN=false only when doctor reports a complete OAuth setup and you intend to call the live API.

First Upload (dry-run walkthrough)

This is the full first-run path. Every step here is dry-run safe — no credentials are required and nothing is sent to YouTube. The output below is captured verbatim from a real run.

1. Check readiness. With no OAuth configured, doctor confirms you are in dry-run mode:

bash
youtube-shorts-agent doctor
json
{  "ok": true,  "dry_run": true,  "configured": {    "client_credentials": "missing",    "access_token": "missing",    "refresh_token": "missing"  },  "missing_count": 3,  "ready_for_live_upload": false,  "next_steps": [    "Current mode is dry-run. Validate metadata and agent flow before live uploads."  ]}

2. Prepare a Short and its caption.

bash
printf 'Launching the agent-first Shorts uploader.\n#shorts #ai #agents' > copy.txt# short.mp4 is your vertical 9:16 clip

3. Run the upload in dry-run. No network call is made; the tool returns the exact job and result it would publish, so an agent can validate metadata before going live:

bash
youtube-shorts-agent upload-short \  --video ./short.mp4 \  --title "Agent-first Shorts upload" \  --caption-file copy.txt \  --tags ai,agents \  --duration 24
json
{  "ok": true,  "dry_run": true,  "job": {    "id": "youtube_1780082215631",    "platform": "youtube",    "status": "queued",    "createdAt": "2026-05-29T19:16:55.631Z",    "caption": "Launching the agent-first Shorts uploader.\n#shorts #ai #agents",    "targetUrl": "",    "mediaPaths": ["./short.mp4"],    "metadata": {      "title": "Agent-first Shorts upload",      "youtube_title": "Agent-first Shorts upload",      "youtube_tags": ["ai", "agents"],      "youtube_contains_synthetic_media": true,      "video_duration_sec": 24,      "video_aspect_ratio": "9:16"    }  },  "result": {    "provider": "youtube_official",    "platformPostId": "dryrun_1780082215631",    "releaseUrl": "https://www.youtube.com",    "raw": { "dryRun": true, "jobId": "youtube_1780082215631" }  }}

platformPostId is prefixed with dryrun_ and releaseUrl is the YouTube root — both signal that nothing was uploaded. The id, createdAt and dryrun_* values vary per run.

4. Confirm the channel listing path (returns an empty list in dry-run):

bash
youtube-shorts-agent list-recent --max-results 5
json
{ "items": [] }

Going live. Configure OAuth (youtube-shorts-agent auth-url --redirect-uri http://localhost:8787/callback, then exchange the callback code for tokens), set YOUTUBE_CLIENT_ID / YOUTUBE_CLIENT_SECRET / YOUTUBE_ACCESS_TOKEN / YOUTUBE_REFRESH_TOKEN in .env, re-run doctor until ready_for_live_upload is true, then set YOUTUBE_DRY_RUN=false and re-run the same upload-short command.

MCP

bash
youtube-shorts-mcp

HTTP (v2 stateless)

Default is stdio. Optional Streamable HTTP — no session id, JSON responses, loopback only:

bash
npx -y -p youtube-shorts-agent youtube-shorts-mcp --http# GET  http://127.0.0.1:3032/health# POST http://127.0.0.1:3032/mcp   (sessionless)

Env: YOUTUBE_MCP_HOST, YOUTUBE_MCP_PORT, YOUTUBE_MCP_TRANSPORT=http.

Hermes-style config:

yaml
mcp_servers:  youtube_shorts:    command: npx    args: ["-y", "youtube-shorts-agent"]    sampling:      enabled: false

Recommended first calls:

  1. youtube_connection_status
  2. youtube_privacy_audit
  3. youtube_upload_short

Agent Surfaces

ToolPurpose
youtube_agent_manifestInstall/runtime guidance for Codex, Claude, Cursor, Hermes and OpenClaw
youtube_connection_statusOAuth and dry-run readiness without token values
youtube_privacy_auditUpload scope, synthetic media and local file boundaries
youtube_oauth_authorize_urlPKCE authorization URL with local session storage
youtube_upload_shortDry-run or live Shorts upload
youtube_list_recent_videosLightweight channel verification

Copy-Paste Agent Prompt

text
Use youtube-shorts-agent. First call youtube_connection_status and youtube_privacy_audit.If uploading AI-generated media, keep containsSyntheticMedia=true. Never print token values.

Configuration

Copy .env.example to .env. Keep .env and .agent-data/ out of Git.

The upload tool sets containsSyntheticMedia=true by default for AI-generated or AI-edited videos. Override only when that is not true for the asset.

Safety Model

  • OAuth tokens are never returned by CLI or MCP tools.
  • PKCE verifier is stored locally in .agent-data/.
  • Live upload requires YOUTUBE_DRY_RUN=false.
  • The package uses the official YouTube Data API and does not automate Studio UI.

Development

bash
npm installnpm testnpm run check

📧 Contact & Support

Source: README.md at commit 26827b4

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.6LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts