MCP Server

Model Context Protocol server so an AI agent can download X (Twitter) videos on your behalf.

Install

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"]
    }
  }
}

Authentication

Run this once first — it opens a device-authorization flow in your browser and saves a bearer token to ~/.x-downloader/config.json. The MCP server reads that same token.

npx -p @roudanio/x-downloader-cli x-downloader auth login

Transport

stdio only — no separate server process or network port. The server talks to xvideodownloader.org's REST API over HTTPS using your saved token.

Tools

download_video

Submit an X/Twitter post URL for download. Optional filename and format overrides require SVIP.

check_status

Poll a download task by id. Repeat until status is "done".

get_download_url

Get the file's download URL for a completed task.

list_downloads

List your recent download history. Requires authentication.

check_usage

Check today's usage against your plan's daily download limit.

Rate limits

Downloads made through the MCP server count against the same free/SVIP daily limits as the website — 2/day on the free plan, unlimited on lifetime SVIP.

Common errors

RATE_LIMIT (daily limit reached), UNSUPPORTED_HOST (only x.com/twitter.com URLs), EMPTY_URL / INVALID_URL_FORMAT (bad input). Tools return these as plain JSON text in the result — check the error or code field.