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.
> ⭐ 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_manifestfor install/runtime guidanceyoutube_connection_statusbefore upload attemptsyoutube_privacy_auditfor local token and media boundariesyoutube_oauth_authorize_urlwith local PKCE session storageyoutube_upload_shortwithcontainsSyntheticMediasupportyoutube_list_recent_videosfor 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 codex
youtube-shorts-agent doctor
youtube-shorts-agent privacy-audit
youtube-shorts-agent auth-url --redirect-uri http://localhost:8787/callback
youtube-shorts-agent upload-short --video ./short.mp4 --title "Launch title" --caption-file copy.txt
youtube-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:
youtube_connection_statusyoutube_privacy_audityoutube_upload_short
Agent Surfaces
| Tool | Purpose |
|---|---|
youtube_agent_manifest |
Install/runtime guidance for Codex, Claude, Cursor, Hermes and OpenClaw |
youtube_connection_status |
OAuth and dry-run readiness without token values |
youtube_privacy_audit |
Upload scope, synthetic media and local file boundaries |
youtube_oauth_authorize_url |
PKCE authorization URL with local session storage |
youtube_upload_short |
Dry-run or live Shorts upload |
youtube_list_recent_videos |
Lightweight 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 install
npm test
npm run check
📧 Contact & Support
- 📨 support@delx.ai — general questions, integration help, partnerships
- 🐛 Bug reports / feature requests — GitHub Issues
- 🐦 Updates — @delx369 on X
- 🌐 Site — wellness.delx.ai
