@roudanio/x-downloader-cli

CLI and MCP server for downloading videos from X (Twitter). Two independent ways to use it:

1. Direct download (x-downloader <url>) — runs your local yt-dlp install. No account, no login, no rate limit — it never talks to xvideodownloader.org.
2. MCP server (x-downloader-mcp) — lets an AI agent call the xvideodownloader.org REST API on your behalf (server-side downloads, subject to that site's free/SVIP plan limits). Requires x-downloader auth login first.

Requirements

• Node.js >= 24 (this package ships raw TypeScript and relies on Node's built-in type stripping — no build step, no npm install compile)
• yt-dlp on your PATH (only needed for direct downloads, not for the MCP server)
• ffmpeg on your PATH (only needed for direct downloads at the default best-quality format; skip with -f best)

Install

npm install -g @roudanio/x-downloader-cli

Or run it without installing:

npx -p @roudanio/x-downloader-cli x-downloader <url>

This exposes three commands: x-downloader, xdown (alias), and x-downloader-mcp.

Direct download

x-downloader https://x.com/user/status/123456789
xdown https://x.com/user/status/123456789 -o ./videos -n clip.mp4
x-downloader https://x.com/user/status/123456789 -F   # list available formats first
x-downloader https://x.com/user/status/123456789 --dry-run   # print the yt-dlp command without running it

| Flag | Description | | --- | --- | | -o, --output <dir> | Output directory (default ~/Downloads) | | -n, --filename <name> | Custom output filename | | -f, --format <format> | yt-dlp format selector (default bestvideo*+bestaudio/best, requires ffmpeg) | | -F, --list-formats | List available formats and exit | | --cookies <file> | Cookies file to pass to yt-dlp | | --proxy <url> | Proxy URL to pass to yt-dlp | | --user-agent <ua> | Custom User-Agent to pass to yt-dlp | | -q, --quiet | Suppress yt-dlp output | | --dry-run | Print the resolved yt-dlp command instead of running it | | -h, --help | Show help | | -v, --version | Show version |

Exit codes

| Code | Meaning | | --- | --- | | 0 | Success | | 1 | Generic error (bad arguments, auth failure, yt-dlp exited with an error) | | 2 | Missing dependency (yt-dlp not found, or ffmpeg missing for the default format) | | other | Passed straight through from the underlying yt-dlp process |

There is no --json / machine-readable output mode yet — output is plain text.

Authentication (for the MCP server)

x-downloader auth login    # opens a device-authorization flow in your browser
x-downloader auth status   # show whether you're logged in and to which server
x-downloader auth logout   # clear the saved token

login requests a device code from xvideodownloader.org, prints a URL and a short code to enter in your browser, then polls until you approve it. The resulting bearer token is saved to ~/.x-downloader/config.json — nothing is ever printed to a config file you'd commit to source control.

MCP server

Add this to your MCP client config (Claude Desktop, Claude Code, Cursor, or any MCP-compatible tool):

{
  "mcpServers": {
    "x-downloader": {
      "command": "npx",
      "args": ["-p", "@roudanio/x-downloader-cli", "x-downloader-mcp"]
    }
  }
}

Run x-downloader auth login once first — the MCP server reads the same saved token. It talks to xvideodownloader.org over stdio (no separate server process, no network port) and exposes 5 tools:

| Tool | Description | | --- | --- | | download_video | Submit an X/Twitter URL for server-side download. filename/format overrides require SVIP. | | check_status | Poll a download task by id until status is "done". | | get_download_url | Get the file's download URL for a completed task (302 redirect, resolved for you). | | list_downloads | List your recent download history (requires auth). | | check_usage | Check today's usage against your plan's daily limit. |

Server-side downloads made through the MCP server count against the same free/SVIP daily limits as the website — see xvideodownloader.org/pricing. Direct downloads (the plain x-downloader <url> command) do not.

More

Full REST API reference, error codes, and request/response schemas: xvideodownloader.org/developers.