search_subreddits

Find Reddit subreddits by name or description, retrieving detailed matches based on specific search parameters and preferences for NSFW or full descriptions.

Instructions

Search for subreddits using either name-based or description-based search.

Args:
    by: Search parameters, either SearchByName or SearchByDescription

Returns:
    List of matching subreddits with their details

Input Schema

TableJSON Schema

Name	Required	Description	Default
`by`	Yes

Implementation Reference

src/reddit_mcp/tools/search_subreddits.py:52-85 (handler)

The core handler function that implements the search_subreddits tool logic. It uses the RedditClient to search subreddits by name or description based on input parameters and maps results to SubredditResult models.

def search_subreddits(by: SearchParams) -> List[SubredditResult]:
    """
    Search for subreddits using either name-based or description-based search.

    Args:
        by: Search parameters, either SearchByName or SearchByDescription

    Returns:
        List of matching subreddits with their details
    """
    client = RedditClient.get_instance()

    if by.type == "name":
        subreddits = client.reddit.subreddits.search_by_name(
            by.query, exact=by.exact_match, include_nsfw=by.include_nsfw
        )
    else:  # by.type == "description"
        subreddits = client.reddit.subreddits.search(by.query)

    return [
        SubredditResult(
            name=subreddit.display_name,
            public_description=subreddit.public_description,
            description=(
                subreddit.description
                if (by.type == "description" and by.include_full_description)
                else None
            ),
            url=subreddit.url,
            subscribers=subreddit.subscribers,
            created_utc=format_utc_timestamp(subreddit.created_utc),
        )
        for subreddit in subreddits
    ]

src/reddit_mcp/tools/search_subreddits.py:23-48 (schema)

Input schema definitions for the tool, discriminating union between SearchByName and SearchByDescription parameters.

class SearchByName(BaseModel):
    """Parameters for searching subreddits by name"""

    type: Literal["name"]
    query: str
    include_nsfw: bool = Field(
        default=False,
        description="Whether to include NSFW subreddits in search results",
    )
    exact_match: bool = Field(
        default=False, description="If True, only return exact name matches"
    )


class SearchByDescription(BaseModel):
    """Parameters for searching subreddits by description"""

    type: Literal["description"]
    query: str
    include_full_description: bool = Field(
        default=False,
        description="Whether to include the full subreddit description (aka sidebar description) in results -- can be very long and contain markdown formatting",
    )


SearchParams = Union[SearchByName, SearchByDescription]

src/reddit_mcp/tools/search_subreddits.py:9-21 (schema)

Output schema model defining the structure of each subreddit result returned by the tool.

class SubredditResult(BaseModel):
    """Subreddit search result"""

    name: str = Field(description="Display name of the subreddit")
    public_description: str = Field(description="Short description shown publicly")
    url: str = Field(description="URL of the subreddit")
    subscribers: int | None = Field(default=None, description="Number of subscribers")
    created_utc: str = Field(description="UTC date when subreddit was created")
    description: str | None = Field(
        default=None,
        description="Full subreddit description with markdown formatting",
    )

src/reddit_mcp/tools/__init__.py:17-24 (registration)
The search_subreddits tool function is included in the central tools registry list, which is imported and used by the MCP server for registration.
```
tools = [
    get_submission,
    get_subreddit,
    get_comments_by_submission,
    get_comment_by_id,
    search_posts,
    search_subreddits,
]
```
src/reddit_mcp/server.py:10-13 (registration)
Generic registration loop in the MCP server that applies mcp.tool() decorator to each function in the tools list, including search_subreddits.
```
for tool in tools:
    logger.info(f"Registering tool: {tool.__name__}")
    mcp.tool()(tool)
```

Reddit MCP