{ "markdown": "\n

YouTube Shorts Agent

\n\n
\n \"YouTube\n
\n\n

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

\n\n

\n \"npm\n \"npm\n \"License\n \"Built\n

\n\n

\n \"GitHub\n \"CI\n \"Part\n \"Category\"\n

\n\n> ⭐ **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.
\n> 🧱 Part of the [Delx agent stack](https://github.com/davidmosiah) — 15 open-source MCP servers across **body, reach and coordination**.\n\n---\n\n\n\nAgent-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.\n\nUse it when an agent needs to prepare, validate or upload Shorts through the official API without touching YouTube Studio UI.\n\n## What Agents Get\n\n- `youtube_agent_manifest` for install/runtime guidance\n- `youtube_connection_status` before upload attempts\n- `youtube_privacy_audit` for local token and media boundaries\n- `youtube_oauth_authorize_url` with local PKCE session storage\n- `youtube_upload_short` with `containsSyntheticMedia` support\n- `youtube_list_recent_videos` for lightweight post-upload checks\n\n## Install\n\n```bash\nnpm install -g youtube-shorts-agent\n```\n\nOr run directly:\n\n```bash\nnpm exec --yes --package=youtube-shorts-agent -- youtube-shorts-agent doctor\n```\n\n## CLI\n\n```bash\nyoutube-shorts-agent manifest --client codex\nyoutube-shorts-agent doctor\nyoutube-shorts-agent privacy-audit\nyoutube-shorts-agent auth-url --redirect-uri http://localhost:8787/callback\nyoutube-shorts-agent upload-short --video ./short.mp4 --title \"Launch title\" --caption-file copy.txt\nyoutube-shorts-agent list-recent --max-results 10\n```\n\nDry-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.\n\n## First Upload (dry-run walkthrough)\n\nThis 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.\n\n**1. Check readiness.** With no OAuth configured, `doctor` confirms you are in dry-run mode:\n\n```bash\nyoutube-shorts-agent doctor\n```\n\n```json\n{\n \"ok\": true,\n \"dry_run\": true,\n \"configured\": {\n \"client_credentials\": \"missing\",\n \"access_token\": \"missing\",\n \"refresh_token\": \"missing\"\n },\n \"missing_count\": 3,\n \"ready_for_live_upload\": false,\n \"next_steps\": [\n \"Current mode is dry-run. Validate metadata and agent flow before live uploads.\"\n ]\n}\n```\n\n**2. Prepare a Short and its caption.**\n\n```bash\nprintf 'Launching the agent-first Shorts uploader.\\n#shorts #ai #agents' > copy.txt\n# short.mp4 is your vertical 9:16 clip\n```\n\n**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:\n\n```bash\nyoutube-shorts-agent upload-short \\\n --video ./short.mp4 \\\n --title \"Agent-first Shorts upload\" \\\n --caption-file copy.txt \\\n --tags ai,agents \\\n --duration 24\n```\n\n```json\n{\n \"ok\": true,\n \"dry_run\": true,\n \"job\": {\n \"id\": \"youtube_1780082215631\",\n \"platform\": \"youtube\",\n \"status\": \"queued\",\n \"createdAt\": \"2026-05-29T19:16:55.631Z\",\n \"caption\": \"Launching the agent-first Shorts uploader.\\n#shorts #ai #agents\",\n \"targetUrl\": \"\",\n \"mediaPaths\": [\"./short.mp4\"],\n \"metadata\": {\n \"title\": \"Agent-first Shorts upload\",\n \"youtube_title\": \"Agent-first Shorts upload\",\n \"youtube_tags\": [\"ai\", \"agents\"],\n \"youtube_contains_synthetic_media\": true,\n \"video_duration_sec\": 24,\n \"video_aspect_ratio\": \"9:16\"\n }\n },\n \"result\": {\n \"provider\": \"youtube_official\",\n \"platformPostId\": \"dryrun_1780082215631\",\n \"releaseUrl\": \"https://www.youtube.com\",\n \"raw\": { \"dryRun\": true, \"jobId\": \"youtube_1780082215631\" }\n }\n}\n```\n\n`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.\n\n**4. Confirm the channel listing path** (returns an empty list in dry-run):\n\n```bash\nyoutube-shorts-agent list-recent --max-results 5\n```\n\n```json\n{ \"items\": [] }\n```\n\n**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.\n\n## MCP\n\n```bash\nyoutube-shorts-mcp\n```\n\n## HTTP (v2 stateless)\n\nDefault is **stdio**. Optional Streamable HTTP — no session id, JSON responses, loopback only:\n\n```bash\nnpx -y -p youtube-shorts-agent youtube-shorts-mcp --http\n# GET http://127.0.0.1:3032/health\n# POST http://127.0.0.1:3032/mcp (sessionless)\n```\n\nEnv: `YOUTUBE_MCP_HOST`, `YOUTUBE_MCP_PORT`, `YOUTUBE_MCP_TRANSPORT=http`.\n\nHermes-style config:\n\n```yaml\nmcp_servers:\n youtube_shorts:\n command: npx\n args: [\"-y\", \"youtube-shorts-agent\"]\n sampling:\n enabled: false\n```\n\nRecommended first calls:\n\n1. `youtube_connection_status`\n2. `youtube_privacy_audit`\n3. `youtube_upload_short`\n\n## Agent Surfaces\n\n| Tool | Purpose |\n|---|---|\n| `youtube_agent_manifest` | Install/runtime guidance for Codex, Claude, Cursor, Hermes and OpenClaw |\n| `youtube_connection_status` | OAuth and dry-run readiness without token values |\n| `youtube_privacy_audit` | Upload scope, synthetic media and local file boundaries |\n| `youtube_oauth_authorize_url` | PKCE authorization URL with local session storage |\n| `youtube_upload_short` | Dry-run or live Shorts upload |\n| `youtube_list_recent_videos` | Lightweight channel verification |\n\n## Copy-Paste Agent Prompt\n\n```text\nUse youtube-shorts-agent. First call youtube_connection_status and youtube_privacy_audit.\nIf uploading AI-generated media, keep containsSyntheticMedia=true. Never print token values.\n```\n\n## Configuration\n\nCopy `.env.example` to `.env`. Keep `.env` and `.agent-data/` out of Git.\n\nThe upload tool sets `containsSyntheticMedia=true` by default for AI-generated or AI-edited videos. Override only when that is not true for the asset.\n\n## Safety Model\n\n- OAuth tokens are never returned by CLI or MCP tools.\n- PKCE verifier is stored locally in `.agent-data/`.\n- Live upload requires `YOUTUBE_DRY_RUN=false`.\n- The package uses the official YouTube Data API and does not automate Studio UI.\n\n## Development\n\n```bash\nnpm install\nnpm test\nnpm run check\n```\n\n---\n\n## 📧 Contact & Support\n\n- 📨 **support@delx.ai** — general questions, integration help, partnerships\n- 🐛 **Bug reports / feature requests** — [GitHub Issues](https://github.com/davidmosiah/youtube-shorts-agent/issues)\n- 🐦 **Updates** — [@delx369](https://x.com/delx369) on X\n- 🌐 **Site** — [wellness.delx.ai](https://wellness.delx.ai)\n\n", "bytes": 8928, "sha": "30c4533375f7fd92120e5ad1d3297724de44982a29f092c04d1858a03fac9c58", "repo_slug": "davidmosiah/youtube-shorts-agent", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_davidmosiah_youtube_shorts_age_c9696971/readme" }