使用说明

Torrent Search MCP Server

A Model Context Protocol (MCP) stdio server for searching torrents using the torrent-search-api library.

Features

Auto-enabled providers: All 10 public providers are automatically enabled on startup:
- 1337x, Eztv, KickassTorrents, Limetorrents, Rarbg
- ThePirateBay, Torrent9, TorrentProject, Torrentz2, Yts
searchTorrent: Search for torrents with enriched results including:
- Torrent details (description, URL)
- Magnet links
- Download information (href)
providerMgt: Comprehensive provider management:
- List all providers (active and inactive)
- Enable/disable providers
- Remove providers
- Load custom providers

CLI harness (default way to search)

scripts/torrent-mcp.mjs is a general stdio client for this MCP server: it spawns index.js, runs the initialize handshake, calls one tool, prints the result, and exits. Use it instead of registering the MCP server with a client. Works from any CWD (bare imports resolve against this repo's node_modules).

ln -sf "$PWD/scripts/torrent-mcp.mjs" ~/.local/bin/torrent-mcp   # once, if ~/.local/bin is on PATH
torrent-mcp search "Beirut A Study of Losses"
torrent-mcp search "Dune Part Two" --category Movies --limit 10
torrent-mcp search "some album" --magnet-only
torrent-mcp search "some album" --json
torrent-mcp call searchTorrent '{"query":"ubuntu","category":"Software","limit":5}'
torrent-mcp tools
torrent-mcp providers list
torrent-mcp providers disable Yts

Flags: --json, --magnet-only, --verbose (server stderr), --timeout <sec> (default 240). Env: TORRENT_MCP_SERVER, TORRENT_MCP_TIMEOUT. Tool errors exit non-zero with the message on stderr. Node >= 18 (uses process.execPath to spawn the server, so no PATH dependency).

Installation

Install dependencies:

npm install

Make the server executable (optional):

chmod +x index.js

Configuration

Optional — only needed if you want this server registered with an MCP client. The CLI harness above already covers search and provider management.

Add this server to your MCP settings file (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "torrent-search": {
      "command": "node",
      "args": ["/home/rjodouin/Documents/git/torrMcp/index.js"]
    }
  }
}

Or if you made it executable:

{
  "mcpServers": {
    "torrent-search": {
      "command": "/home/rjodouin/Documents/git/torrMcp/index.js"
    }
  }
}

Tools

1. searchTorrent

Search for torrents and get enriched results.

Parameters:

query (required): Search query for the torrent
category (optional): Category to search in (All, Movies, TV, Music, Games, Software). Default: "All"
limit (optional): Maximum number of results to return. Default: 20

Returns: Each torrent result includes:

Basic info: title, size, seeds, peers, time, provider
details: Description and URL from getTorrentDetails
magnet: Magnet link from getMagnet
download: href and note for downloadTorrent

Example usage:

{
  "name": "searchTorrent",
  "arguments": {
    "query": "ubuntu",
    "category": "Software",
    "limit": 10
  }
}

2. providerMgt

Manage torrent search providers.

Parameters:

action (required): One of: "list", "enable", "disable", "remove", "loadCustom"
providerName (required for enable/disable/remove): Name of the provider
customProvidersPath (required for loadCustom): Path to custom providers file

Actions:

list

Get all available providers and active providers.

{
  "name": "providerMgt",
  "arguments": {
    "action": "list"
  }
}

enable

Enable a specific provider.

{
  "name": "providerMgt",
  "arguments": {
    "action": "enable",
    "providerName": "ThePirateBay"
  }
}

disable

Disable a specific provider.

{
  "name": "providerMgt",
  "arguments": {
    "action": "disable",
    "providerName": "ThePirateBay"
  }
}

remove

Remove a provider completely.

{
  "name": "providerMgt",
  "arguments": {
    "action": "remove",
    "providerName": "CustomProvider"
  }
}

loadCustom

Load custom providers from a file.

{
  "name": "providerMgt",
  "arguments": {
    "action": "loadCustom",
    "customProvidersPath": "/path/to/custom/providers.json"
  }
}

Testing

You can test the server directly using the MCP inspector or by integrating it with an MCP-compatible client.

Manual testing with stdio

node index.js

Then send MCP protocol messages via stdin.

Available Providers

The torrent-search-api library includes several built-in providers. Use the providerMgt tool with action "list" to see all available providers.

Common providers include:

ThePirateBay
1337x
Torrentz2
TorrentProject
And more...

Notes

Some providers may not support all features (e.g., magnet links)
Provider availability depends on network access and provider status
Results are returned asynchronously and may take a few seconds
Error handling is built-in for failed provider operations
Important: Many torrent sites use Cloudflare or similar protection that may block automated requests. This is a limitation of the underlying torrent-search-api library and not the MCP server itself. Different providers may have different availability.

Verification

Run the verification script to test the basic functionality:

node verify.js

This will test provider management and attempt a simple search.

License

MIT

Credits

Built on top of torrent-search-api by Jimmy Laurent.