fleapit

<p align="center"> <img src="assets/logo-flea.svg" alt="" width="112" height="112"> </p>

<h1 align="center">fleapit</h1>

<p align="center"><b>The seediest cinema in your terminal.</b></p>

A fleapit is British slang for the scruffy neighborhood picture-house — sticky floors, creaky seats, but it played everything and everyone secretly loved it. This fleapit is an MCP server that lets any terminal AI agent find torrents, download them, and stream video straight to VLC. And yes: every show here is powered by seeders.

• Search — curated scrapers (vendored from torlink, MIT): YTS, The Pirate Bay, 1337x, EZTV, Nyaa, SubsPlease, FitGirl, BitTorrented. Results come back with size, seeders, and ready-to-use magnet links.
• Download — WebTorrent under the hood; downloads run in the background inside the server process, saved to ~/Downloads by default.
• Stream — a local HTTP server with Range support streams any video file while it downloads; VLC launches automatically and playback starts within seconds.

What it looks like

Once fleapit is hooked up, you just talk to your agent:

"Find me Big Buck Bunny and play it" → agent calls search_torrents, picks the healthiest result, calls stream_torrent — VLC opens and playback starts while the download runs behind it.

"Download the latest SubsPlease release of that show" → search_torrents with category: "anime", then download_torrent; the file lands in ~/Downloads.

"How are my downloads doing?" → list_downloads — progress, speed, ETA, peers.

"That torrent has 12 episodes, play episode 3" → list_files to see indexes, then stream_torrent with fileIndex.

Requirements

• Node.js ≥ 20
• VLC for streaming (brew install --cask vlc on macOS) — downloads work without it, and stream_torrent still returns a URL any player can open

Hook it up to your agent

fleapit is on npm — no clone, no build. The server speaks MCP over stdio, so it works with every MCP-capable agent.

Claude Code:

claude mcp add fleapit -- npx -y fleapit

Gemini CLI — ~/.gemini/settings.json:

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

Codex CLI — ~/.codex/config.toml:

[mcp_servers.fleapit]
command = "npx"
args = ["-y", "fleapit"]

OpenCode — opencode.json:

{
  "mcp": {
    "fleapit": { "type": "local", "command": ["npx", "-y", "fleapit"] }
  }
}

Claude Code plugin — same MCP server, but also ships the torrents usage skill that teaches Claude when to search vs. download vs. stream. No clone, no build; paste both lines into Claude Code:

/plugin marketplace add nikets40/fleapit
/plugin install fleapit@niket-tools

Tools

Tool	What it does
search_torrents	Search all (or one category of) sources; sorted by seeders, deduped by infohash
download_torrent	Add a magnet/infohash and download in the background
stream_torrent	Stream the (largest) video file to VLC while downloading
list_files	List files in a torrent, with indexes for stream_torrent
list_downloads	Progress, speed, ETA, peers for everything active
control_torrent	pause / resume / remove (keep files) / delete (remove files)

Configuration

Env var	Effect
FLEAPIT_DIR	Default download folder (default: ~/Downloads)
VLC_PATH	Explicit VLC binary if it's not on the default path

How it works

One Node process is the whole machine. The MCP server owns a lazy WebTorrent client; search_torrents fans out to the vendored scrapers in parallel (a dead source is reported, never fatal) and merges results by seeders. stream_torrent adds the magnet, waits for metadata, picks the largest video file, and starts a loopback-only HTTP server with Range support in front of file.createReadStream — WebTorrent prioritizes the pieces behind whatever byte range the player asks for, so seeking works and playback starts long before the download finishes. VLC is launched pointing at that URL (open -a VLC on macOS, VLC_PATH override anywhere).

Development

npm run dev        # run from source (tsx)
npm run typecheck  # tsc --noEmit
npm run build      # bundle to dist/ (tsup)

Layout: src/index.ts (MCP tools) → src/engine.ts (WebTorrent wrapper) → src/stream-server.ts (Range streaming) + src/vlc.ts (player launch). Search scrapers live in src/vendor/sources/, one file per source with a common Source interface — adding a source means one new file and one line in registry.ts.

Troubleshooting

• "No results" — a source may be blocked on your network; the response's sourcesOffline says which. Try another category or query.
• Metadata timeout on stream/download — weak swarm. Pick a result with more seeders.
• VLC doesn't open — install VLC or set VLC_PATH; the stream URL in the response works in any player (QuickTime, mpv, a browser).
• WebRTC peers — the optional node-datachannel native module adds WebRTC peer support. If your npm blocks its install script, everything still works over TCP/uTP/DHT.

Notes

• Torrents are active only while the server runs; re-adding a magnet resumes from whatever file data is already on disk.
• The stream URL binds to 127.0.0.1 only.
• Search scrapers in src/vendor/ are vendored from torlink (MIT — see src/vendor/TORLINK-LICENSE); diff against upstream occasionally to pick up scraper fixes.
• What you download is your responsibility. Several of the indexed sources list copyrighted material.