reddit-mcp-server

Instructions

Implementation Reference

• src/index.ts:179-224 (registration)

  Registration of the 'get_user_posts' tool in the FastMCP server, including name, description, Zod input schema, and the inline execute handler function.

  server.addTool({
    name: "get_user_posts",
    description: "Get recent posts by a Reddit user with sorting and filtering options",
    parameters: z.object({
      username: z.string().describe("The Reddit username (without u/ prefix)"),
      sort: z.enum(["new", "hot", "top"]).default("new").describe("Sort order for posts"),
      time_filter: z
        .enum(["hour", "day", "week", "month", "year", "all"])
        .default("all")
        .describe("Time filter 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.getUserPosts(args.username, {
        sort: args.sort,
        timeFilter: args.time_filter,
        limit: args.limit,
      })
  
      if (posts.length === 0) {
        return `No posts found for u/${args.username} with the specified filters.`
      }
  
      const postSummaries = posts
        .map((post, index) => {
          const flags = [...(post.over18 ? ["**NSFW**"] : []), ...(post.spoiler ? ["**Spoiler**"] : [])]
  
          return `### ${index + 1}. ${post.title} ${flags.join(" ")}
  - Subreddit: r/${post.subreddit}
  - Score: ${post.score.toLocaleString()} (${(post.upvoteRatio * 100).toFixed(1)}% upvoted)
  - Comments: ${post.numComments.toLocaleString()}
  - Posted: ${new Date(post.createdUtc * 1000).toLocaleString()}
  - Link: https://reddit.com${post.permalink}`
        })
        .join("\n\n")
  
      return `# Posts by u/${args.username} (${args.sort} - ${args.time_filter})
  
  ${postSummaries}`
    },
  })

• src/index.ts:191-223 (handler)

  The handler function (execute callback) that implements the core logic: gets Reddit client, fetches user posts, formats them into a markdown summary, and returns the response.

    execute: async (args) => {
      const client = getRedditClient()
      if (!client) {
        throw new Error("Reddit client not initialized")
      }
  
      const posts = await client.getUserPosts(args.username, {
        sort: args.sort,
        timeFilter: args.time_filter,
        limit: args.limit,
      })
  
      if (posts.length === 0) {
        return `No posts found for u/${args.username} with the specified filters.`
      }
  
      const postSummaries = posts
        .map((post, index) => {
          const flags = [...(post.over18 ? ["**NSFW**"] : []), ...(post.spoiler ? ["**Spoiler**"] : [])]
  
          return `### ${index + 1}. ${post.title} ${flags.join(" ")}
  - Subreddit: r/${post.subreddit}
  - Score: ${post.score.toLocaleString()} (${(post.upvoteRatio * 100).toFixed(1)}% upvoted)
  - Comments: ${post.numComments.toLocaleString()}
  - Posted: ${new Date(post.createdUtc * 1000).toLocaleString()}
  - Link: https://reddit.com${post.permalink}`
        })
        .join("\n\n")
  
      return `# Posts by u/${args.username} (${args.sort} - ${args.time_filter})
  
  ${postSummaries}`
    },

• src/index.ts:182-190 (schema)

  Zod schema defining the input parameters for the get_user_posts tool.

  parameters: z.object({
    username: z.string().describe("The Reddit username (without u/ prefix)"),
    sort: z.enum(["new", "hot", "top"]).default("new").describe("Sort order for posts"),
    time_filter: z
      .enum(["hour", "day", "week", "month", "year", "all"])
      .default("all")
      .describe("Time filter for top posts"),
    limit: z.number().min(1).max(100).default(10).describe("Number of posts to retrieve"),
  }),

• src/client/reddit-client.ts:689-739 (helper)

  Supporting method in RedditClient class that performs the actual API call to fetch user's submitted posts from Reddit.

  async getUserPosts(
    username: string,
    options: {
      sort?: string
      timeFilter?: string
      limit?: number
    } = {},
  ): Promise<RedditPost[]> {
    await this.authenticate()
    try {
      const { sort = "new", timeFilter = "all", limit = 25 } = options
      const params = new URLSearchParams({
        sort,
        t: timeFilter,
        limit: limit.toString(),
      })
  
      const response = await this.makeRequest(`/user/${username}/submitted.json?${params}`)
      if (!response.ok) {
        throw new Error(`HTTP ${response.status}`)
      }
  
      const json = (await response.json()) as { data: { children: any[] } }
  
      return json.data.children
        .filter((child: any) => child.kind === "t3")
        .map((child: any) => {
          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 {
      throw new Error(`Failed to get posts for user ${username}`)
    }
  }