reddit-mcp-server

Instructions

Implementation Reference

• src/index.ts:439-494 (registration)

  Registration of the 'search_reddit' MCP tool using server.addTool, including name, description, Zod input schema, and inline execute handler that calls the RedditClient search method and formats results.
  server.addTool({ name: "search_reddit", description: "Search Reddit for posts and content across subreddits", parameters: z.object({ query: z.string().describe("Search query"), subreddit: z.string().optional().describe("Limit search to specific subreddit (without r/ prefix)"), sort: z.enum(["relevance", "hot", "top", "new", "comments"]).default("relevance").describe("Sort order"), time_filter: z.enum(["hour", "day", "week", "month", "year", "all"]).default("all").describe("Time filter"), limit: z.number().min(1).max(100).default(10).describe("Number of results"), type: z.enum(["link", "sr", "user"]).default("link").describe("Type of content to search"), }), execute: async (args) => { const client = getRedditClient() if (!client) { throw new Error("Reddit client not initialized") } if (!args.query || args.query.trim() === "") { throw new Error("Search query cannot be empty") } const posts = await client.searchReddit(args.query, { subreddit: args.subreddit, sort: args.sort, timeFilter: args.time_filter, limit: args.limit, type: args.type, }) if (posts.length === 0) { const searchLocation = args.subreddit ? ` in r/${args.subreddit}` : "" return `No results found for "${args.query}"${searchLocation}.` } const searchResults = posts .map((post, index) => { const flags = [...(post.over18 ? ["**NSFW**"] : []), ...(post.spoiler ? ["**Spoiler**"] : [])] return `### ${index + 1}. ${post.title} ${flags.join(" ")} - Subreddit: r/${post.subreddit} - Author: u/${post.author} - 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") const searchLocation = args.subreddit ? ` in r/${args.subreddit}` : "" return `# Reddit Search Results for: "${args.query}"${searchLocation} Sorted by: ${args.sort} | Time: ${args.time_filter} | Type: ${args.type} ${searchResults}` }, })
• src/index.ts:442-449 (schema)

  Zod schema defining the input parameters for the search_reddit tool.
  parameters: z.object({ query: z.string().describe("Search query"), subreddit: z.string().optional().describe("Limit search to specific subreddit (without r/ prefix)"), sort: z.enum(["relevance", "hot", "top", "new", "comments"]).default("relevance").describe("Sort order"), time_filter: z.enum(["hour", "day", "week", "month", "year", "all"]).default("all").describe("Time filter"), limit: z.number().min(1).max(100).default(10).describe("Number of results"), type: z.enum(["link", "sr", "user"]).default("link").describe("Type of content to search"), }),
• src/client/reddit-client.ts:548-605 (handler)

  The core handler function in RedditClient that executes the Reddit API search request, handles authentication, constructs query parameters, fetches results, and maps to RedditPost objects.
  async searchReddit( query: string, options: { subreddit?: string sort?: string timeFilter?: string limit?: number type?: string } = {}, ): Promise<RedditPost[]> { await this.authenticate() try { const { subreddit, sort = "relevance", timeFilter = "all", limit = 25, type = "link" } = options const endpoint = subreddit ? `/r/${subreddit}/search.json` : "/search.json" const params = new URLSearchParams({ q: query, sort, t: timeFilter, limit: limit.toString(), type, ...(subreddit && { restrict_sr: "true" }), }) const response = await this.makeRequest(`${endpoint}?${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") // Only posts .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 search Reddit for: ${query}`) } }
• src/index.ts:450-494 (helper)

  The MCP tool's execute handler that validates input, calls the RedditClient.searchReddit helper, and formats the markdown search results output.
  execute: async (args) => { const client = getRedditClient() if (!client) { throw new Error("Reddit client not initialized") } if (!args.query || args.query.trim() === "") { throw new Error("Search query cannot be empty") } const posts = await client.searchReddit(args.query, { subreddit: args.subreddit, sort: args.sort, timeFilter: args.time_filter, limit: args.limit, type: args.type, }) if (posts.length === 0) { const searchLocation = args.subreddit ? ` in r/${args.subreddit}` : "" return `No results found for "${args.query}"${searchLocation}.` } const searchResults = posts .map((post, index) => { const flags = [...(post.over18 ? ["**NSFW**"] : []), ...(post.spoiler ? ["**Spoiler**"] : [])] return `### ${index + 1}. ${post.title} ${flags.join(" ")} - Subreddit: r/${post.subreddit} - Author: u/${post.author} - 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") const searchLocation = args.subreddit ? ` in r/${args.subreddit}` : "" return `# Reddit Search Results for: "${args.query}"${searchLocation} Sorted by: ${args.sort} | Time: ${args.time_filter} | Type: ${args.type} ${searchResults}` }, })