reddit-mcp-server

Instructions

Implementation Reference

• src/index.ts:327-368 (handler)

  Registration, schema definition, and handler (execute function) for the MCP tool 'get_top_posts'. Fetches top posts via RedditClient and formats the response.

  server.addTool({
    name: "get_top_posts",
    description: "Get top posts from a subreddit or from the Reddit home feed",
    parameters: z.object({
      subreddit: z.string().optional().describe("The subreddit name (without r/ prefix). Leave empty for home feed"),
      time_filter: z
        .enum(["hour", "day", "week", "month", "year", "all"])
        .default("week")
        .describe("Time period for top posts"),
      limit: z.number().min(1).max(100).default(10).describe("Number of posts to retrieve"),
    }),
    execute: async (args) => {
      const client = getRedditClient()
      if (!client) {
        throw new Error("Reddit client not initialized")
      }
  
      const posts = await client.getTopPosts(args.subreddit || "", args.time_filter, args.limit)
  
      if (posts.length === 0) {
        const location = args.subreddit ? `r/${args.subreddit}` : "home feed"
        return `No posts found in ${location} for the specified time period.`
      }
  
      const formattedPosts = posts.map(formatPostInfo)
      const postSummaries = formattedPosts
        .map(
          (post, index) => `### ${index + 1}. ${post.title}
  - Author: u/${post.author}
  - Score: ${post.stats.score.toLocaleString()} (${(post.stats.upvoteRatio * 100).toFixed(1)}% upvoted)
  - Comments: ${post.stats.comments.toLocaleString()}
  - Posted: ${post.metadata.posted}
  - Link: ${post.links.shortLink}`,
        )
        .join("\n\n")
  
      const location = args.subreddit ? `r/${args.subreddit}` : "Home Feed"
      return `# Top Posts from ${location} (${args.time_filter})
  
  ${postSummaries}`
    },
  })

• src/client/reddit-client.ts:186-227 (helper)

  Core helper function in RedditClient that implements the API call to retrieve top posts from a subreddit or the home feed using Reddit's /top.json endpoint.

  async getTopPosts(subreddit: string, timeFilter: string = "week", limit: number = 10): Promise<RedditPost[]> {
    await this.authenticate()
    try {
      const endpoint = subreddit ? `/r/${subreddit}/top.json` : "/top.json"
      const params = new URLSearchParams({
        t: timeFilter,
        limit: limit.toString(),
      })
  
      const response = await this.makeRequest(`${endpoint}?${params}`)
      if (!response.ok) {
        throw new Error(`HTTP ${response.status}`)
      }
  
      const json = (await response.json()) as RedditApiListingResponse<RedditApiPostData>
  
      return json.data.children.map((child) => {
        const post = child.data
        return {
          id: post.id,
          title: post.title,
          author: post.author,
          subreddit: post.subreddit,
          selftext: post.selftext,
          url: post.url,
          score: post.score,
          upvoteRatio: post.upvote_ratio,
          numComments: post.num_comments,
          createdUtc: post.created_utc,
          over18: post.over_18,
          spoiler: post.spoiler,
          edited: !!post.edited,
          isSelf: post.is_self,
          linkFlairText: post.link_flair_text ?? undefined,
          permalink: post.permalink,
        }
      })
    } catch {
      // Failed to get top posts
      throw new Error(`Failed to get top posts for ${subreddit || "home"}`)
    }
  }