Model Context Protocol (MCP)

TorrPlay includes a built-in Model Context Protocol (MCP) server, allowing AI assistants (such as Claude Desktop, Cursor, and IDE coding agents) to interact with your running TorrPlay instance.

Through the MCP server, AI assistants can query your torrent library, inspect streaming status and piece caching, add or manage torrents, and generate stream URLs directly from natural language prompts.

Architecture

The MCP server runs as a separate CLI subcommand:

torrplay mcp [flags]

• Client-Application Decoupling: The MCP server communicates with the main TorrPlay application over HTTP/REST. It does not open the database directly, avoiding lock contention and port conflicts with the running server.
• Transports:
  • stdio (default): Standard input/output transport, designed for local desktop clients such as Claude Desktop.
  • sse: Server-Sent Events transport over HTTP, binding strictly to a local loopback address for network-based AI clients.

CLI Options & Environment Variables

Available Capabilities

Tools

• list_torrents: List all active and stored torrents with status, progress, and file lists.
• get_torrent: Retrieve detailed metadata, piece cache state, and file structure for a specific torrent.
• add_torrent: Add a torrent using a magnet URI or info hash.
• delete_torrent: Remove a torrent and release its cached pieces from memory.
• update_torrent: Modify metadata such as titles, categories, and poster URLs.
• get_stream_url: Generate direct HTTP stream URLs with valid scoped playback tokens for specified video files.
• preload_torrent: Start or replace a file preload, optionally around a saved playback position.
• get_preload_status: Read the current preload state, progress, peer counts, and download rate.
• cancel_preload: Cancel a torrent preload and release its reserved memory and priorities.
• get_memory_stats: Inspect RAM cache usage, limits, and piece-buffer statistics.
• get_torrent_stats: Inspect download speed, peers, readers, and piece state for one torrent.
• get_system_info: Read the application version, build, uptime, and deployment information.
• get_system_logs: Search retained application logs and filter them by level.
• get_system_metrics: Read current torrent activity and network transfer rates.

Resources

• torrplay://torrents: Real-time list of all torrents in the active library.
• torrplay://torrents/{hash}: Detailed state of an individual torrent.
• torrplay://system/memory: Current RAM piece cache utilization and LRU eviction status.
• torrplay://system/info: Application version, build, uptime, and deployment information.
• torrplay://system/logs: Most recent retained application log entries.
• torrplay://system/metrics: Current torrent activity and network transfer rates.

Prompts

• find_playable_file: Inspects a torrent, identifies its primary video file, and prepares a stream URL for it.
• stream_diagnostics: Evaluates peer, piece, reader, and memory statistics to diagnose playback stalls.

Authentication

The MCP client sends TORRPLAY_TOKEN as an HTTP Bearer credential on every API request. When authentication is enabled, configure TorrPlay to use Bearer authentication and supply an administrative JWT obtained from /oauth/token. Playback and Stremio tokens are restricted to media routes and cannot authorize MCP management tools. The built-in MCP client does not send Basic Authentication credentials.

Setup with Claude Desktop

To configure TorrPlay MCP with Claude Desktop, add the following entry to your claude_desktop_config.json:

{
  "mcpServers": {
    "torrplay": {
      "command": "/usr/local/bin/torrplay",
      "args": ["mcp"],
      "env": {
        "TORRPLAY_URL": "http://127.0.0.1:8090",
        "TORRPLAY_TOKEN": "your-jwt-token-if-enabled"
      }
    }
  }
}

Replace /usr/local/bin/torrplay with the absolute path to your TorrPlay binary. Once added, restart Claude Desktop. The TorrPlay tools will become available in the chat interface.

Running SSE Transport

For agents or applications that connect over SSE:

torrplay mcp -transport sse -addr 127.0.0.1:8091 -url http://127.0.0.1:8090