Reddit MCP Tool

Instructions

Implementation Reference

• reddit_mcp/server.py:286-342 (handler)

  The FastMCP tool handler for 'get_hot_reddit_posts', decorated with @mcp.tool(). Handles input validation via type hints, client initialization check, fetches posts via RedditClient, formats output as a human-readable string, and includes comprehensive error handling.

  @mcp.tool()
  async def get_hot_reddit_posts(subreddit: str, limit: int = 10) -> str:
      """
      Get hot posts from a subreddit
  
      Args:
          subreddit: The name of the subreddit (without r/)
          limit: Number of posts to return (default: 10, max: 100)
  
      Returns:
          Human readable string containing hot posts
      """
      if reddit_client is None:
          return """Error: Reddit client not initialized. 
  
  To fix this:
  1. Copy env.example to .env: cp env.example .env
  2. Edit .env with your Reddit API credentials:
     - Get credentials from https://old.reddit.com/prefs/apps/
     - Create a 'script' type app
     - Fill in REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET, and REDDIT_USER_AGENT
  3. Restart the MCP server
  
  Example .env content:
  REDDIT_CLIENT_ID=your_14_char_client_id
  REDDIT_CLIENT_SECRET=your_27_char_client_secret  
  REDDIT_USER_AGENT=reddit-mcp-tool:v0.2.0 (by /u/yourusername)"""
      
      try:
          posts = await reddit_client.get_hot_posts(subreddit, min(limit, 100))
          
          if not posts:
              return f"No hot posts found in r/{subreddit}"
          
          result = f"Hot posts from r/{subreddit}:\n\n"
          
          for i, post in enumerate(posts, 1):
              result += (
                  f"{i}. **{post['title']}**\n"
                  f"   Author: {post['author']}\n"
                  f"   Score: {post['score']} (upvote ratio: {post['upvote_ratio']:.0%})\n"
                  f"   Comments: {post['num_comments']}\n"
                  f"   Link: {post['permalink']}\n"
              )
              
              if post['selftext'] and len(post['selftext']) > 0:
                  preview = post['selftext'][:150] + "..." if len(post['selftext']) > 150 else post['selftext']
                  result += f"   Content: {preview}\n"
              
              result += "\n"
          
          return result
          
      except Exception as e:
          logger.error(f"Error getting hot posts from r/{subreddit}: {str(e)}")
          return f"Error getting hot posts from r/{subreddit}: {str(e)}"

• reddit_mcp/reddit_client.py:124-152 (helper)

  Core helper method in RedditClient class that performs the actual Reddit API call using asyncpraw to fetch hot posts from a subreddit and structures the data into a standardized list of dictionaries.

  async def get_hot_posts(self, subreddit_name: str, limit: int = 10) -> List[Dict[str, Any]]:
      """Get hot posts from a subreddit."""
      try:
          subreddit = await self.reddit.subreddit(subreddit_name)
          
          posts = []
          async for submission in subreddit.hot(limit=limit):
              post_data = {
                  "id": submission.id,
                  "title": submission.title,
                  "author": str(submission.author) if submission.author else "[deleted]",
                  "score": submission.score,
                  "upvote_ratio": submission.upvote_ratio,
                  "url": submission.url,
                  "permalink": f"https://reddit.com{submission.permalink}",
                  "created_utc": submission.created_utc,
                  "num_comments": submission.num_comments,
                  "selftext": submission.selftext[:200] + "..." if len(submission.selftext) > 200 else submission.selftext,
                  "is_self": submission.is_self,
                  "domain": submission.domain,
                  "subreddit": str(submission.subreddit),
              }
              posts.append(post_data)
          
          return posts
          
      except Exception as e:
          raise Exception(f"Error getting hot posts from r/{subreddit_name}: {str(e)}")