fileclaw

Ask your AI to find you any file on the internet. It does.

fileclaw is an MCP server that gives Claude, Codex, Gemini CLI, Cursor, Windsurf, and any MCP-compatible client the ability to search 28 sources, download files, and stream video — all through natural conversation. Books, papers, movies, TV, anime, manga, music, games, ROMs, software, subtitles — if it's out there, fileclaw can probably find it.

What it looks like

You: Find me the EPUB of "Designing Data-Intensive Applications"

Claude: Found it on Library Genesis (14MB, EPUB). Downloading now... saved to ~/Downloads/

You: Get me Sintel in 1080p

Claude: Found on YTS (1.4GB, 1080p BluRay). Sending to Real-Debrid... download complete.

You: Stream Big Buck Bunny

Claude: Found a 1080p copy. Opening in VLC now.

You: I need the paper with DOI 10.1038/nature12373

Claude: Found on Sci-Hub. Downloaded PDF to ~/Downloads/

You: Find me all papers on imagery rehearsal therapy

Claude: Found 35 papers via Semantic Scholar. Downloading 28 PDFs from Sci-Hub... saved to ~/Downloads/papers/

You: Get me the full discography in FLAC

Claude: Found 9 studio albums via MusicBrainz. Searching for a complete discography pack... found one (12GB, FLAC). Sending to Real-Debrid.

No manual searching, no navigating sketchy sites, no configuring torrent clients. Just ask your AI.

How it works

You  -->  Claude / Codex / Gemini CLI  -->  fileclaw  -->  28 sources
                          |                |
                    identify first    LibGen, Sci-Hub, Anna's Archive,
                    (TMDb, MAL,      YTS, Nyaa, The Pirate Bay, FitGirl,
                     MusicBrainz,    Internet Archive, MangaDex, Soulseek, ...
                     CrossRef, ...)          |
                                       Download via:
                                 Direct HTTP / Real-Debrid /
                                  Usenet / Torrent client

1. You ask your AI for something in plain language
2. If the query is ambiguous, fileclaw identifies it first — resolving titles to exact matches using metadata APIs (TMDb, MusicBrainz, CrossRef, MyAnimeList, Open Library, Wikidata)
3. fileclaw searches the right sources for that type of content
4. Results are deduplicated, ranked, and the best match is picked
5. The file is downloaded through whatever method works — direct download, Real-Debrid, usenet, or torrent client
6. You get notified when it's done

fileclaw learns over time: sources that deliver good results get ranked higher in future searches.

Install

Quickest way

npx fileclaw setup

Interactive wizard — configures downloads, registers the MCP server with Claude Desktop or Claude Code. Done in under a minute.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Restart Claude Desktop. Ask Claude to find something.

Troubleshooting: "Failed to spawn process" / "No such file or directory"

Desktop apps (Claude, Cursor, etc.) don't inherit your shell's PATH. If you manage Node with fnm, nvm, or volta, npx won't be found. Fix options:

• Use bunx instead (if you have Bun installed via Homebrew):

  { "command": "bunx", "args": ["fileclaw", "--mcp"] }

• Use the full path to npx (find it with which npx in your terminal):

  { "command": "/Users/you/.local/share/fnm/aliases/default/bin/npx", "args": ["-y", "fileclaw", "--mcp"] }

• Use the standalone binary — no Node/Bun required (see below)

Claude Code

claude mcp add fileclaw -- npx -y fileclaw --mcp

OpenAI Codex

codex mcp add fileclaw -- npx -y fileclaw --mcp

Gemini CLI

Add to ~/.gemini/settings.json:

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

Cursor / Windsurf

Both support MCP servers. Add to your project's .cursor/mcp.json or .windsurf/mcp.json:

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

Any MCP-compatible client

fileclaw speaks standard MCP over stdio. Point your client at:

npx -y fileclaw --mcp

Note: The MCP server loads code once at startup. If you edit source files, restart the server for changes to take effect — restart your MCP client or start a new session.

Standalone binary

Download from GitHub Releases — no Node/Bun required.

./fileclaw search "sintel" --type=video
./fileclaw --mcp   # start as MCP server

What it can find

Books & papers — LibGen, Sci-Hub, Anna's Archive, Internet Archive Search by title, author, ISBN, or DOI. Direct downloads, no torrenting needed.

Movies & TV — YTS, EZTV, The Pirate Bay, Nyaa, Stremio addons, Torrents-CSV Finds the best quality available. Streams directly to VLC/mpv or downloads via Real-Debrid.

Music — Soulseek, AudioBookBay, Piped, Librivox, Nyaa, Internet Archive Soulseek gives you lossless FLAC from a massive P2P network. AudioBookBay for audiobooks. Librivox for free public domain audiobooks.

Anime & manga — Nyaa, MangaDex, WeebCentral Torrents for anime, chapter-by-chapter reads or bulk downloads for manga.

Games — FitGirl, DODI, Myrient, RomHeaven, MarioCube Repacked PC games and retro ROMs for every console.

Software — FileCR, The Pirate Bay, Torrents-CSV, Internet Archive Mac and PC applications.

Subtitles — OpenSubtitles, YTS-Subs Auto-matched to your downloads by language preference.

Power-user sources — Prowlarr, Newznab indexers Prowlarr aggregates dozens of torrent and usenet indexers behind a single API. Newznab gives direct access to usenet indexers like NZBgeek. Both need an API key or self-hosted instance.

19 of the 28 sources work with zero configuration. For the rest, you just need an API key.

Smart disambiguation

fileclaw identifies what you're looking for before searching. Ask for something ambiguous and it resolves it first:

• Papers — resolves titles to DOIs via CrossRef and Semantic Scholar, then fetches the exact PDF from Sci-Hub
• TV/Film — uses TMDb (or Wikidata as keyless fallback) to distinguish movies from TV shows, find seasons, and resolve filmographies
• Music — queries MusicBrainz for artists, albums, and full discographies
• Anime/Manga — uses MyAnimeList to disambiguate between anime series, movies, OVAs, and manga
• Games — resolves platforms, editions, and full franchise lists via Wikidata
• Software — identifies versions, platforms, and licenses via Wikidata
• Books — resolves authors and series via Open Library

Collections

Find entire collections in one step:

• Discographies — all albums by an artist, filtered by format
• TV seasons — all episodes in a season, with pack-first search
• Filmographies — all movies by a director or actor
• Book series — all works by an author or in a series
• Game franchises — all titles in a series, with platform info
• Manga series — all chapters or volumes

fileclaw searches for complete packs first (most efficient), then falls back to individual item searches in parallel.

Post-download tools

fileclaw doesn't stop at downloading — it can organize your files too:

• extract — unpack archives (zip, rar, 7z, tar.gz). Detects format from magic bytes. Choose whether to delete originals.
• organize — rename and move files using metadata and naming templates. Built-in Plex/Jellyfin-compatible defaults, or specify your own (e.g. Movies/{title} ({year})/{title}.{ext}). Supports dry-run preview.
• shelve — add books to your Calibre library with metadata (title, authors, ISBN, tags, series). Optionally converts format (e.g. EPUB → MOBI for Kindle).

You: Extract that game repack and delete the archive

Claude: Extracted 47 files (18.2 GB) to ~/Downloads/Elden Ring. Original archive deleted.

You: Organize that movie for Plex

Claude: Moved to ~/Downloads/Movies/Inception (2010)/Inception (2010).mkv

Academic tools

Built-in research workflow powered by Semantic Scholar:

• research — search papers by topic, author, or institution
• literature_review — map a research topic with clustering, seminal papers, and citation analysis. Auto-downloads PDFs via Sci-Hub/LibGen when requested.
• cite_chase — follow citation chains forward and backward from a paper
• download_papers — batch download PDFs by DOI via Sci-Hub, LibGen, and Anna's Archive

Optional Zotero integration for managing your library.

Download methods

fileclaw routes downloads automatically based on what you have configured:

| Method | Best for | Setup | |--------|----------|-------| | Direct HTTP | Books, papers, subtitles | Nothing — works out of the box | | Real-Debrid | Movies, TV, games, software | API key (~$3/mo) — recommended for torrents | | Usenet | Everything | NZBGet or SABnzbd + indexer | | Torrent client | Everything | qBittorrent or Transmission |

Real-Debrid is the easiest upgrade: it downloads torrents in the cloud and gives you a fast direct link. No torrent client needed.

Configuration

~/.config/fileclaw/config.json — or just ask Claude to run setup() and it walks you through it conversationally.

{
  "download_dir": "~/Downloads",

  // Torrent downloads via Real-Debrid (recommended)
  "realdebrid": {
    "api_key": "YOUR_KEY",
    "prefer": true
  },

  // Usenet (pick one)
  "usenet": {
    "type": "sabnzbd",           // "nzbget", "nzbget-cli", or "sabnzbd"
    "url": "http://localhost:8080",
    "api_key": "YOUR_KEY"
  },

  // Extra sources that need API keys
  "sources": {
    "newznab": [
      { "name": "nzbgeek", "url": "https://api.nzbgeek.info", "api_key": "YOUR_KEY" }
    ],
    "opensubtitles": { "api_key": "YOUR_KEY" }
  },

  // Media player for streaming (auto-detected if omitted)
  "player": "vlc",

  // Optional: TMDb API key for richer TV/film identification (free at themoviedb.org)
  // Without it, Wikidata is used as a fallback — still works, just less detailed
  "tmdb_api_key": "YOUR_TMDB_KEY",

  // Optional: FlareSolverr for bypassing Cloudflare on protected sources (e.g. DODI)
  // Run via Docker: docker run -p 8191:8191 ghcr.io/flaresolverr/flaresolverr
  "flaresolverr": { "url": "http://localhost:8191/v1" }
}

{ "sources": { "tpb": false } }

NZBGet CLI (lightest — no daemon):

{ "usenet": { "type": "nzbget-cli" } }

Needs brew install nzbget and ~/.nzbget with your usenet server credentials.

NZBGet daemon:

{ "usenet": { "type": "nzbget", "url": "http://localhost:6789", "username": "nzbget", "password": "tegbzn6789" } }

SABnzbd:

{ "usenet": { "type": "sabnzbd", "url": "http://localhost:8080", "api_key": "YOUR_SAB_API_KEY" } }

CLI

fileclaw also works as a standalone command-line tool:

fileclaw search "machine learning" --type=book
fileclaw stream "big buck bunny" --player=vlc
fileclaw scan ~/Downloads/file.mkv
fileclaw health
fileclaw stats
fileclaw setup

Safety

Downloaded files can be scanned for security issues — magic byte mismatches, embedded executables, and media codec validation via ffprobe. Just ask your AI to scan a file, or use fileclaw scan <file>.

Development

git clone https://codeberg.org/rzacharias/fileclaw && cd fileclaw
bun install
bun run cli search "sintel"          # CLI from source
bun run dev                          # MCP server (stdio)
bun run typecheck                    # type check
SKIP_INTEGRATION=1 bun test          # unit tests (219 tests)
bun test                             # all tests including integration
bun run build                        # bundle dist/

Architecture

src/
  sources/       28 source implementations — each exports search(), healthCheck(), resolve()
  metadata/      Disambiguation resolvers (TMDb, MusicBrainz, Open Library, CrossRef, Jikan, Wikidata)
  academic/      Semantic Scholar client, Zotero integration
  tools/         Core logic: search, download, stream, scan
  mcp/           MCP server + 19 tool registrations
  download/      Download routing: Real-Debrid, usenet, torrent client
  http.ts        Shared HTTP client with Cloudflare detection + FlareSolverr fallback
  config.ts      User config (~/.config/fileclaw/config.json)
  quality.ts     Source ranking — learns from usage over time

Each source is a self-contained module that implements a shared Source interface. Adding a new source is ~100 lines of TypeScript. See CONTRIBUTING.md.

Contributing

Want to add a source? Each source is a single file (~50 lines of real code) that implements a search() and healthCheck() method. There's a copy-paste template ready to go.

fileclaw contribute add mysite https://...    # scaffold a new source from template
fileclaw contribute check libgen              # diagnose a broken source
fileclaw contribute pr                        # fork + commit + open PR

Check out the good first issues or source requests for ideas, or request a new source yourself.

See CONTRIBUTING.md for the full guide.

License

MIT