Overview

Put.io MCP Server provides a lightweight HTTP service that lets you add and manage torrent transfers in a Put.io account. It acts as an intermediary between tools (indexers, browser extensions, automation scripts, home servers) and the Put.io API, exposing a small set of endpoints to submit magnet links or torrent files, monitor transfer status, and receive callbacks when transfers change state.

The server is designed for automation and integration: it can be deployed behind HTTPS, configured with an API token, and wired into other systems to securely and reliably hand off downloads to your Put.io account. This simplifies automating downloads from search/index sites, integrating with local clients, and tracking transfer progress centrally.

Features

Submit magnet links or upload .torrent files to your Put.io account
Authenticate using a Put.io OAuth token (configurable via environment)
Simple token-based protection for incoming requests (MCP token)
Poll or webhook-style notifications on transfer state changes
Health and metrics endpoints for monitoring
Docker-friendly or run from source with minimal dependencies
Configurable logging and base URL for reverse-proxy deployments

Installation / Configuration

Below are common ways to run the MCP server. Adjust environment variables to match your deployment.

Clone and run from source (Node.js example):

git clone https://github.com/putdotio/putio-mcp-server.git
cd putio-mcp-server
# install dependencies (example)
npm ci
# start
PUTIO_TOKEN=your_putio_oauth_token MCP_TOKEN=your_mcp_token PORT=3000 npm start

Run with Docker:

docker run -d \
  --name putio-mcp \
  -p 3000:3000 \
  -e PUTIO_TOKEN=your_putio_oauth_token \
  -e MCP_TOKEN=your_mcp_token \
  -e BASE_URL=https://mcp.example.com \
  putdotio/putio-mcp-server:latest

Docker Compose example:

version: "3.7"
services:
  putio-mcp:
    image: putdotio/putio-mcp-server:latest
    environment:
      - PUTIO_TOKEN=${PUTIO_TOKEN}
      - MCP_TOKEN=${MCP_TOKEN}
      - PORT=3000
      - BASE_URL=https://mcp.example.com
    ports:
      - "3000:3000"

Common environment variables

Variable	Purpose	Example
PUTIO_TOKEN	OAuth token for your Put.io account	abcdef123456
MCP_TOKEN	Shared token used to authorize incoming requests	mysecret
PORT	HTTP port to listen on	3000
BASE_URL	Public URL behind a reverse proxy	https://mcp.example.com
LOG_LEVEL	Logging verbosity (info, debug, error)	info

If exposing the server to the internet, protect it with TLS or run behind a reverse proxy (nginx, Traefik) and restrict allowed origins/IPs where possible.

Available Tools

The server exposes a small REST surface for integration. Below is a typical set of endpoints — actual paths may vary per release; consult the repository for exact routes.

Method	Path	Purpose
POST	/mcp/add	Add a magnet link (or URL) to your Put.io account
POST	/mcp/upload	Upload a .torrent file for addition
GET	/mcp/status/:id	Query transfer status by Put.io transfer id
GET	/mcp/list	List recent transfers for the account
POST	/mcp/webhook/test	Send a test webhook callback (for debugging)
GET	/health	Basic health check
GET	/metrics	Prometheus-style metrics (if enabled)

Authentication:

Requests should include the MCP token in an Authorization header (e.g., Authorization: Bearer <MCP_TOKEN>), or via a configurable header depending on your deployment.

Example: add a magnet link via curl

curl -X POST https://mcp.example.com/mcp/add \
  -H "Authorization: Bearer my_mcp_token" \
  -H "Content-Type: application/json" \
  -d '{"magnet":"magnet:?xt=urn:btih:...","path":"/Downloads"}'

Upload a .torrent file:

curl -X POST https://mcp.example.com/mcp/upload \
  -H "Authorization: Bearer my_mcp_token" \
  -F "file=@/path/to/file.torrent"

Use Cases

Automate adding new releases from an indexer:
- Configure the indexer to call the MCP endpoint when a new item appears; MCP forwards the magnet to your Put.io account so downloads begin immediately.
Browser extension integration:
- A lightweight browser extension posts the active page’s magnet link to the MCP endpoint, avoiding storing OAuth credentials in the extension.
Home server automation:
- Wrap MCP calls in a Home Assistant or Node-RED flow to trigger notifications when a transfer completes, then move or transcode files.
CI/CD or scripted workflows:
- Add torrents as part of a build or release pipeline (for internal testing artifacts hosted on BitTorrent), and track progress via the status API.

Example webhook payload (on transfer completion)

{
  "transfer_id": 123456,
  "status": "COMPLETED",
  "name": "example.iso",
  "size": 1073741824,
  "downloaded": 1073741824,
  "download_speed": 0
}

Resources

Source and issues: https://github.com/putdotio/putio-mcp-server
Put.io API docs: refer to your Put.io account/app settings for OAuth token guidance
Recommended

Put.io MCP Server: Download Torrents From Account