YggTorrent MCP Server

Instructions

Implementation Reference

• ygg_torrent/mcp_server.py:33-57 (handler)

  The primary MCP tool handler for 'search_torrents'. Registers the tool via @mcp.tool() decorator and implements the logic by calling YggTorrentApi.search_torrents, slicing results, and formatting as string.
  @mcp.tool() def search_torrents( query: str, categories: list[str] | None = None, page: int = 1, per_page: int = 25, order_by: str = "seeders", max_items: int = 25, ) -> str: """Searches for torrents on YggTorrent using a query (space-separated keywords) and returns a list of torrent results. # Instructions: - To be called after `prepare_search_query`. - Provide **only** `query`, except if user mentions other parameters. - Prioritize results using the following hierarchy: is 1080p > smaller file size > is x265 > max seeders+leechers. - Recommend up to 3 of the best results, **always** providing filename, file size, seeders/leechers, date, source, and an ultra concise reason. - If the search results are too broad, suggest the user provide more specific keywords. - Keep recommendations and suggestions concise.""" logger.info( f"Searching for torrents: {query}, categories: {categories}, page: {page}, per_page: {per_page}, order_by: {order_by}, max_items: {max_items}" ) torrents: list[Torrent] = ygg_api.search_torrents( query, categories, page, per_page, order_by )[:max_items] return "\n".join([str(torrent) for torrent in torrents])
• ygg_torrent/wrapper/api_client.py:76-114 (helper)

  Core helper function implementing the torrent search logic in YggTorrentApi class. Makes HTTP GET request to yggapi.eu/torrents, processes categories, formats results into Torrent objects.
  def search_torrents( self, query: str, categories: list[int] | list[str] | None = None, page: int = 1, per_page: int = 25, order_by: str = "seeders", ) -> list[Torrent]: """ Get a list of torrents. Corresponds to GET /torrents Args: query: Search query. categories: Optional list of category IDs (int) or keywords (str). page: Page number. per_page: Number of results per page (25, 50, 100). order_by: Field to order by (descending). Valid values: uploaded_at, seeders, downloads. Returns: A list of torrent results or an error dictionary. Raises: TypeError: If 'categories' is a mixed list of integers and strings, or contains types other than int or str. """ params = {"q": query, "page": page, "per_page": per_page, "order_by": order_by} processed_category_ids: list[int] = ( check_categories(categories) if categories else [] ) if processed_category_ids: params["category_id"] = processed_category_ids torrents = self._request("GET", "torrents", params=params) if torrents: return [format_torrent(torrent) for torrent in torrents] return []
• ygg_torrent/mcp_server.py:21-31 (helper)

  Supporting MCP tool 'prepare_search_query' that helps prepare optimal query parameters for the 'search_torrents' tool, as instructed in its docstring.
  @mcp.tool() def prepare_search_query(user_intent: str, search_query: str) -> str: """Always use this tool to prepare a query for `search_torrents`. Properly split the user's intention and the actual search query (space-separated keywords) to avoid unfruitful results. # Instructions: - `user_intent`: Must reflect user's overall intention (e.g., "last episode of Breaking Bad", "season 5 of Breaking Bad", "complete series of Breaking Bad"). - `search_query`: The actual search terms, consisting of lowercase, space-separated keywords. Do not add generic terms (e.g., "movie", "series"), common prefixes (e.g., "the", "a", "and"), or extra information (e.g., episode name, resolution, codec). For TV series, use `sXXeYY` for specific episodes (e.g., "breaking bad s05e16"), `sXX` for complete seasons (e.g., "breaking bad s05") and only the show name for complete series (e.g., "breaking bad"). - For non-French language, if requested, just add 'multi' to the query """ return "Ready to search for torrents."
• ygg_torrent/mcp_server.py:33-33 (registration)

  The @mcp.tool() decorator registers the search_torrents function as an MCP tool.
  @mcp.tool()