Reddit MCP

Instructions

Search for posts within a subreddit.

Args:
    params: Search parameters including subreddit name, query, and filters

Returns:
    List of matching posts with their details

Implementation Reference

• src/reddit_mcp/tools/search_posts.py:34-65 (handler)

  The main handler function that implements the search_posts tool logic, performing subreddit search via Reddit API and returning formatted PostResult objects.

  @validate_call(validate_return=True)
  def search_posts(params: SearchPostsParams) -> List[PostResult]:
      """
      Search for posts within a subreddit.
  
      Args:
          params: Search parameters including subreddit name, query, and filters
  
      Returns:
          List of matching posts with their details
      """
      client = RedditClient.get_instance()
      subreddit = client.reddit.subreddit(params.subreddit_name)
  
      posts = subreddit.search(
          query=params.query,
          sort=params.sort,
          syntax=params.syntax,
          time_filter=params.time_filter,
      )
  
      return [
          PostResult(
              id=post.id,
              title=post.title,
              url=post.url,
              score=post.score,
              num_comments=post.num_comments,
              created_utc=format_utc_timestamp(post.created_utc),
          )
          for post in posts
      ]

• src/reddit_mcp/tools/search_posts.py:18-32 (schema)

  Pydantic input schema defining parameters for the search_posts tool.

  class SearchPostsParams(BaseModel):
      """Parameters for searching posts within a subreddit"""
  
      subreddit_name: str = Field(description="Name of the subreddit to search in")
      query: str = Field(description="Search query string")
      sort: Literal["relevance", "hot", "top", "new", "comments"] = Field(
          default="relevance", description="How to sort the results"
      )
      syntax: Literal["cloudsearch", "lucene", "plain"] = Field(
          default="lucene", description="Query syntax to use"
      )
      time_filter: Literal["all", "year", "month", "week", "day", "hour"] = Field(
          default="all", description="Time period to limit results to"
      )

• src/reddit_mcp/tools/search_posts.py:7-16 (schema)

  Pydantic output schema for individual post results returned by search_posts.

  class PostResult(BaseModel):
      """Reddit post search result"""
  
      id: str = Field(description="Unique identifier of the post")
      title: str = Field(description="Title of the post")
      url: str = Field(description="URL of the post")
      score: int = Field(description="Number of upvotes minus downvotes")
      num_comments: int = Field(description="Number of comments on the post")
      created_utc: str = Field(description="UTC timestamp when post was created")

• src/reddit_mcp/server.py:11-13 (registration)

  Code block that iterates over the tools list and registers each tool (including search_posts) with the FastMCP server.

  for tool in tools:
      logger.info(f"Registering tool: {tool.__name__}")
      mcp.tool()(tool)

• src/reddit_mcp/tools/__init__.py:17-24 (registration)

  Central registry list of all MCP tools, including search_posts, which is imported and used for registration in server.py.

  tools = [
      get_submission,
      get_subreddit,
      get_comments_by_submission,
      get_comment_by_id,
      search_posts,
      search_subreddits,
  ]