Reddit MCP Server

Instructions

Args:
    username: The username of the Reddit user (with or without 'u/' prefix)
    sort: Sort order for comments - one of: "new", "hot", "top", "controversial"
    time_filter: Time period to filter comments (e.g. "hour", "day", "week", "month", "year", "all")
    limit: Number of comments to return (1-100)

Returns:
    Dictionary containing structured comment history with the following structure:
    {
        'username': str,  # The username
        'sort': str,  # Sort method used
        'time_filter': str,  # Time filter used
        'comments': [  # List of comments
            {
                'id': str,  # Comment ID
                'body': str,  # Comment text content
                'author': str,  # Author's username
                'subreddit': str,  # Subreddit where comment was posted
                'score': int,  # Comment score (upvotes - downvotes)
                'created_utc': float,  # Comment creation timestamp
                'permalink': str,  # Relative URL to the comment
                'link_title': str,  # Title of the post being commented on
                'link_id': str,  # ID of the post
                'parent_id': str,  # ID of parent comment or post
                'is_submitter': bool,  # Whether commenter is the post author
                'stickied': bool,  # Whether comment is stickied
                'distinguished': Optional[str],  # Distinguishing type (e.g., 'moderator')
                'edited': bool,  # Whether comment has been edited
                'gilded': int,  # Number of times gilded
                'controversiality': int,  # Controversy score
                'depth': int,  # Comment depth in thread (0 for top-level)
            },
            ...
        ],
        'metadata': {
            'fetched_at': float,  # Timestamp when data was fetched
            'comment_count': int,  # Number of comments returned
        }
    }

Raises:
    ValueError: If username is invalid, sort method is invalid, or time_filter is invalid
    RuntimeError: For other errors during the operation

Implementation Reference

• server.py:419-558 (handler)

  The core handler function decorated with @mcp.tool(), which implements the logic to retrieve and format a specified user's Reddit comments based on sort order, time filter, and limit. It validates inputs, fetches data using PRAW Reddit API, structures the response with comment details, and includes metadata.

  @mcp.tool()
  def get_user_comments(
      username: str,
      sort: str = "new",
      time_filter: str = "all",
      limit: int = 25,
  ) -> Dict[str, Any]:
      """Get a user's comment history.
  
      Args:
          username: The username of the Reddit user (with or without 'u/' prefix)
          sort: Sort order for comments - one of: "new", "hot", "top", "controversial"
          time_filter: Time period to filter comments (e.g. "hour", "day", "week", "month", "year", "all")
          limit: Number of comments to return (1-100)
  
      Returns:
          Dictionary containing structured comment history with the following structure:
          {
              'username': str,  # The username
              'sort': str,  # Sort method used
              'time_filter': str,  # Time filter used
              'comments': [  # List of comments
                  {
                      'id': str,  # Comment ID
                      'body': str,  # Comment text content
                      'author': str,  # Author's username
                      'subreddit': str,  # Subreddit where comment was posted
                      'score': int,  # Comment score (upvotes - downvotes)
                      'created_utc': float,  # Comment creation timestamp
                      'permalink': str,  # Relative URL to the comment
                      'link_title': str,  # Title of the post being commented on
                      'link_id': str,  # ID of the post
                      'parent_id': str,  # ID of parent comment or post
                      'is_submitter': bool,  # Whether commenter is the post author
                      'stickied': bool,  # Whether comment is stickied
                      'distinguished': Optional[str],  # Distinguishing type (e.g., 'moderator')
                      'edited': bool,  # Whether comment has been edited
                      'gilded': int,  # Number of times gilded
                      'controversiality': int,  # Controversy score
                      'depth': int,  # Comment depth in thread (0 for top-level)
                  },
                  ...
              ],
              'metadata': {
                  'fetched_at': float,  # Timestamp when data was fetched
                  'comment_count': int,  # Number of comments returned
              }
          }
  
      Raises:
          ValueError: If username is invalid, sort method is invalid, or time_filter is invalid
          RuntimeError: For other errors during the operation
      """
      manager = RedditClientManager()
      if not manager.client:
          raise RuntimeError("Reddit client not initialized")
  
      # Validate username
      if not username or not isinstance(username, str) or username.startswith((" ", "/")):
          raise ValueError("Invalid username provided")
  
      # Clean username
      clean_username = username[2:] if username.startswith("u/") else username
  
      # Validate sort method
      valid_sort = ["new", "hot", "top", "controversial"]
      if sort not in valid_sort:
          raise ValueError(
              f"Invalid sort method: {sort}. Must be one of: {', '.join(valid_sort)}"
          )
  
      # Validate time_filter
      valid_time_filters = ["hour", "day", "week", "month", "year", "all"]
      if time_filter not in valid_time_filters:
          raise ValueError(
              f"Invalid time_filter: {time_filter}. Must be one of: {', '.join(valid_time_filters)}"
          )
  
      # Clamp limit to valid range
      limit = max(1, min(100, limit))
  
      try:
          logger.info(
              f"Getting {limit} {sort} comments for u/{clean_username} (time_filter={time_filter})"
          )
          user = manager.client.redditor(clean_username)
  
          # Get comments based on sort method
          if sort == "new":
              comments = user.comments.new(limit=limit)
          elif sort == "hot":
              comments = user.comments.hot(limit=limit)
          elif sort == "top":
              comments = user.comments.top(time_filter=time_filter, limit=limit)
          elif sort == "controversial":
              comments = user.comments.controversial(time_filter=time_filter, limit=limit)
  
          # Convert to list and format
          comments_list = list(comments)
          formatted_comments = []
  
          for comment in comments_list:
              comment_data = {
                  "id": comment.id,
                  "body": comment.body,
                  "author": comment.author.name if comment.author else "[deleted]",
                  "subreddit": comment.subreddit.display_name,
                  "score": comment.score,
                  "created_utc": comment.created_utc,
                  "permalink": comment.permalink,
                  "link_title": getattr(comment, "link_title", ""),
                  "link_id": comment.link_id,
                  "parent_id": comment.parent_id,
                  "is_submitter": comment.is_submitter,
                  "stickied": comment.stickied,
                  "distinguished": comment.distinguished,
                  "edited": bool(comment.edited),
                  "gilded": getattr(comment, "gilded", 0),
                  "controversiality": getattr(comment, "controversiality", 0),
                  "depth": getattr(comment, "depth", 0),
              }
              formatted_comments.append(comment_data)
  
          return {
              "username": clean_username,
              "sort": sort,
              "time_filter": time_filter,
              "comments": formatted_comments,
              "metadata": {
                  "fetched_at": time.time(),
                  "comment_count": len(formatted_comments),
              },
          }
  
      except Exception as e:
          logger.error(f"Error getting comments for u/{clean_username}: {e}")
          if "NOT_FOUND" in str(e) or "USER_DOESNT_EXIST" in str(e):
              raise ValueError(f"User u/{clean_username} not found") from e
          raise RuntimeError(f"Failed to get user comments: {e}") from e

• server.py:426-471 (schema)

  The docstring of the get_user_comments function defines the input schema (parameters with types and descriptions), output structure (detailed JSON schema), and possible errors, serving as the tool's schema definition.

  """Get a user's comment history.
  
  Args:
      username: The username of the Reddit user (with or without 'u/' prefix)
      sort: Sort order for comments - one of: "new", "hot", "top", "controversial"
      time_filter: Time period to filter comments (e.g. "hour", "day", "week", "month", "year", "all")
      limit: Number of comments to return (1-100)
  
  Returns:
      Dictionary containing structured comment history with the following structure:
      {
          'username': str,  # The username
          'sort': str,  # Sort method used
          'time_filter': str,  # Time filter used
          'comments': [  # List of comments
              {
                  'id': str,  # Comment ID
                  'body': str,  # Comment text content
                  'author': str,  # Author's username
                  'subreddit': str,  # Subreddit where comment was posted
                  'score': int,  # Comment score (upvotes - downvotes)
                  'created_utc': float,  # Comment creation timestamp
                  'permalink': str,  # Relative URL to the comment
                  'link_title': str,  # Title of the post being commented on
                  'link_id': str,  # ID of the post
                  'parent_id': str,  # ID of parent comment or post
                  'is_submitter': bool,  # Whether commenter is the post author
                  'stickied': bool,  # Whether comment is stickied
                  'distinguished': Optional[str],  # Distinguishing type (e.g., 'moderator')
                  'edited': bool,  # Whether comment has been edited
                  'gilded': int,  # Number of times gilded
                  'controversiality': int,  # Controversy score
                  'depth': int,  # Comment depth in thread (0 for top-level)
              },
              ...
          ],
          'metadata': {
              'fetched_at': float,  # Timestamp when data was fetched
              'comment_count': int,  # Number of comments returned
          }
      }
  
  Raises:
      ValueError: If username is invalid, sort method is invalid, or time_filter is invalid
      RuntimeError: For other errors during the operation
  """

• server.py:419-419 (registration)

  The @mcp.tool() decorator registers the get_user_comments function as an MCP tool with the FastMCP server instance 'mcp'.

  @mcp.tool()