torrentclaw-mcp

Model Context Protocol server for TorrentClaw — giving AI assistants the ability to search movies and TV shows, find torrents with magnet links, check streaming availability, and explore cast/crew metadata.

torrentclaw-mcp is developed by TorrentClaw as part of its open-source ecosystem. It wraps the TorrentClaw API into the MCP standard so that any compatible AI assistant (Claude, GPT, etc.) can access the platform's search and discovery features natively.

Quick Start

npx torrentclaw-mcp

No API key required (optional for higher rate limits).

What can it do?

Tools

| Tool | Description | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | search_content | Search movies/shows with filters (query, type, genre, year, rating, quality, language, audio, HDR, season, episode, sort). Returns torrents, magnet links, and optional streaming info. | | autocomplete | Type-ahead search suggestions (up to 8 results). Use to validate titles before a full search. | | get_popular | Get popular content ranked by user clicks | | get_recent | Get recently added content | | get_watch_providers | Streaming availability by country (Netflix, Disney+, etc.) | | get_credits | Cast and director for a title | | get_torrent_url | Get .torrent file download URL from info hash | | track_interaction | Track user interaction with a torrent (magnet click, download, copy) | | submit_scan_request | Submit a torrent for audio/video quality analysis via TrueSpec | | get_scan_status | Check the status of a torrent scan request |

Resources

| URI | Description | | --------------------- | ----------------------------------------------------- | | torrentclaw://stats | Catalog statistics (content/torrent counts by source) |

Prompts

| Prompt | Description | | ---------------- | -------------------------------------------------------- | | search_movie | Search for a movie by title and get torrents + streaming | | search_show | Search for a TV show by title and get torrents | | whats_new | Discover recently added movies and TV shows | | where_to_watch | Find where to stream, rent, or buy a title |

Configuration

Claude Desktop

Add to claude_desktop_config.json:

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

Claude Code

Add to .mcp.json or ~/.claude/settings.json:

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

Environment Variables

| Variable | Default | Description | | --------------------- | ------------------------- | -------------------------------------------------------------- | | TORRENTCLAW_API_URL | https://torrentclaw.com | Base URL of the TorrentClaw API | | TORRENTCLAW_API_KEY | (none) | Optional API key for authenticated access (higher rate limits) |

Project Structure

.
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── config.ts             # Configuration & URL validation
│   ├── api-client.ts         # TorrentClaw API client with caching
│   ├── types.ts              # TypeScript interfaces for API responses
│   ├── prompts.ts            # MCP prompt definitions
│   ├── tools/                # MCP tool implementations
│   │   ├── search-content.ts
│   │   ├── autocomplete.ts
│   │   ├── get-popular.ts
│   │   ├── get-recent.ts
│   │   ├── get-watch-providers.ts
│   │   ├── get-credits.ts
│   │   ├── get-torrent-url.ts
│   │   ├── track-interaction.ts
│   │   └── scan-request.ts
│   ├── formatters/           # Output formatting
│   │   ├── content.ts
│   │   ├── providers.ts
│   │   └── credits.ts
│   └── resources/            # MCP resources
│       └── stats.ts
├── tests/                    # Test suite (vitest)
├── .github/workflows/        # CI/CD (lint, build, test, release)
├── lefthook.yml              # Git hooks (commit lint, prettier, tsc)
├── Makefile                  # Dev workflow (build, test, lint, fmt)
├── CONTRIBUTING.md           # Contribution guidelines
├── LICENSE                   # MIT
└── README.md

Development

git clone https://github.com/torrentclaw/torrentclaw-mcp.git
cd torrentclaw-mcp
make install-tools
make hooks
make build && make test

Test with MCP Inspector:

npx @modelcontextprotocol/inspector node build/index.js

About TorrentClaw

TorrentClaw is an open platform focused on improving the quality and reliability of torrent metadata. Our mission is to make torrent search engines more accurate and the torrent ecosystem healthier — by building tools that verify, enrich, and standardize metadata across the network.

torrentclaw-mcp is part of the TorrentClaw open-source ecosystem, alongside TrueSpec (torrent metadata verification).

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License — see LICENSE for details.