Terminal UI MCP Server

The torrent client your
terminal deserves.

Clitorrents is a fast, opinionated torrent client with a gorgeous TUI and a full MCP server — so you can search from the keyboard, or tell Hermes to grab that totally legal documentary for tonight.

Get started View on GitHub v0.4.2
Clitorrents TUI loading screen

Two ways to torrent

Keyboard warrior or AI delegator. Your call.

Same background daemon, same downloads, same impeccable taste in Creative Commons cinema. Use the TUI when you want to feel powerful. Use MCP when you'd rather outsource the vibe check to your agent.

Terminal User Interface

A full-featured TUI built with Ink. Search providers, browse results, manage transfers, tweak ratios, and open your download folder — all without leaving the terminal.

  • Tab through Search → Results → Transfers
  • Sparklines, peer lists, and ETA porn
  • Ctrl+Q quits the UI; downloads keep running
  • Ctrl+O opens the settings editor inline

MCP Server

Plug Clitorrents into Cursor, Claude Desktop, OpenClaw, Hermes — whatever speaks MCP. Your agent gets tools to search, add, pause, and monitor torrents while you pretend to work.

  • search, add_torrent, list_transfers
  • Live status via the same background daemon
  • One-line npx setup — no install required
  • Perfect for "find me something legal to watch tonight"
Hermes · MCP connected · clitorrents
Hey, can you find a totally legal copy of Sintel and start downloading it? I have rights. Probably.
On it. Searching providers… found 12 results. Adding Sintel (2010) [1080p] to your Movies folder.
Download started. ETA ~6 minutes. I'll ping you when it's ready for popcorn.

Demo

See it in action

Search, add, and monitor transfers — all from one keyboard-driven layout.

Full walkthrough — from splash screen to live downloads

Under the hood

Incredible. Also, practical.

Clitorrents isn't just a pretty face in monospace. There's a proper architecture underneath — because someone has to keep seeding while you're in a meeting.

Background daemon

One WebTorrent engine on 127.0.0.1:17359. TUI, MCP, and CLI all connect to it. Close the UI; downloads continue.

SSE live updates

Server-Sent Events push transfer progress in real time. No websocket drama. Just vibes and throughput.

Smart categories

Auto-route TV, movies, and music to separate folders based on torrent name heuristics. Your NAS will thank you.

Provider search

Multi-provider fallback search. When one indexer is having a day, Clitorrents tries the next one.

Ratio & limits

Per-torrent ratio caps, global bandwidth throttles, and sensible seed-stop policies. Seed responsibly.

Offline-aware

Detects network loss, pauses torrents, and polls gently until you're back online. Laptop-friendly.

Get it running

Commands to glory

No install required if you're feeling lazy. Homebrew if you're feeling civilised. Global npm if you're feeling committed.

bash — clitorrents

# Run the TUI — zero install

npx clitorrents

# Or kick off the MCP server

npx clitorrents mcp
bash — homebrew

# macOS and Linux

brew install j-norwood-young/tap/clitorrents
clitorrents
bash — npm global
npm install -g clitorrents
clitorrents
clitorrents search "creative commons documentary" --limit 10
clitorrents download sintel --pick 1 --dir ./downloads
json — mcp.json

// Cursor (.cursor/mcp.json) or Claude Desktop config

{
  "mcpServers": {
    "clitorrents": {
      "command": "npx",
      "args": ["-y", "clitorrents", "mcp"]
    }
  }
}

Requires Node.js 20+. The daemon auto-starts on first use. Stop everything with clitorrents stop.

MCP tools

search add_torrent list_transfers transfer_status pause_torrent resume_torrent remove_torrent set_limits get_config set_config
Legal notice: Clitorrents is a tool. Use it only for content you have the right to access. We are very pro "totally legal movies" and very anti "please don't sue us." You know the drill.