search_reddit
Find Reddit posts by keywords, subreddits, or filters to gather insights and information from discussions across the platform.
Instructions
Search for posts across Reddit or specific subreddits. Returns matching posts with content and metadata.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| author | No | Filter by specific username (e.g., "spez") | |
| flair | No | Filter by post flair/tag (e.g., "Discussion", "News") | |
| limit | No | Number of results (1-100, default: 25) | |
| query | Yes | Search terms (e.g., "machine learning", "climate change") | |
| sort | No | Result ordering: "relevance" (best match), "hot", "top", "new", "comments" (most discussed) | |
| subreddits | No | List of subreddits to search in. Leave empty to search all of Reddit (e.g., ["science", "technology"]) | |
| time | No | Time range filter: "hour", "day", "week", "month", "year", "all" |
Input Schema (JSON Schema)
{
"properties": {
"author": {
"description": "Filter by specific username (e.g., \"spez\")",
"type": "string"
},
"flair": {
"description": "Filter by post flair/tag (e.g., \"Discussion\", \"News\")",
"type": "string"
},
"limit": {
"description": "Number of results (1-100, default: 25)",
"type": "number"
},
"query": {
"description": "Search terms (e.g., \"machine learning\", \"climate change\")",
"type": "string"
},
"sort": {
"description": "Result ordering: \"relevance\" (best match), \"hot\", \"top\", \"new\", \"comments\" (most discussed)",
"enum": [
"relevance",
"hot",
"top",
"new",
"comments"
],
"type": "string"
},
"subreddits": {
"description": "List of subreddits to search in. Leave empty to search all of Reddit (e.g., [\"science\", \"technology\"])",
"items": {
"type": "string"
},
"type": "array"
},
"time": {
"description": "Time range filter: \"hour\", \"day\", \"week\", \"month\", \"year\", \"all\"",
"enum": [
"hour",
"day",
"week",
"month",
"year",
"all"
],
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
}
Implementation Reference
- src/tools/index.ts:123-206 (handler)The main handler function implementing the search_reddit tool logic: performs Reddit search via API, handles multiple subreddits, applies filters for author and flair, extracts and formats post data.async searchReddit(params: z.infer<typeof searchRedditSchema>) { // Handle multiple subreddits let results: RedditListing<RedditPost>; if (params.subreddits && params.subreddits.length > 0) { if (params.subreddits.length === 1) { // Single subreddit - direct search results = await this.api.search(params.query, { subreddit: params.subreddits[0], sort: params.sort, time: params.time, limit: params.limit, }); } else { // Multiple subreddits - parallel search const searchPromises = params.subreddits.map(sub => this.api.search(params.query, { subreddit: sub, sort: params.sort, time: params.time, limit: Math.ceil(params.limit! / params.subreddits!.length), }) ); const allResults = await Promise.all(searchPromises); // Combine results results = { kind: 'Listing', data: { children: allResults.flatMap(r => r.data.children), after: null, before: null, } }; } } else { // Search all of Reddit results = await this.api.search(params.query, { subreddit: undefined, sort: params.sort, time: params.time, limit: params.limit, }); } // Filter by author if specified if (params.author) { results.data.children = results.data.children.filter( child => child.data.author.toLowerCase() === params.author!.toLowerCase() ); } // Filter by flair if specified if (params.flair) { results.data.children = results.data.children.filter( child => child.data.link_flair_text?.toLowerCase().includes(params.flair!.toLowerCase()) ); } // Extract just the essential fields from Reddit's verbose response const posts = results.data.children.map(child => ({ id: child.data.id, title: child.data.title, author: child.data.author, score: child.data.score, upvote_ratio: child.data.upvote_ratio, num_comments: child.data.num_comments, created_utc: child.data.created_utc, url: child.data.url, permalink: `https://reddit.com${child.data.permalink}`, subreddit: child.data.subreddit, is_video: child.data.is_video, is_text_post: child.data.is_self, content: child.data.selftext?.substring(0, 500), // Limit text preview nsfw: child.data.over_18, link_flair_text: child.data.link_flair_text, })); return { results: posts, total_results: posts.length }; }
- src/tools/index.ts:20-28 (schema)Zod schema defining the input parameters and validation for the search_reddit tool.export const searchRedditSchema = z.object({ query: z.string().describe('Search query'), subreddits: z.array(z.string()).optional().describe('Subreddits to search in (leave empty for all)'), sort: z.enum(['relevance', 'hot', 'top', 'new', 'comments']).optional().default('relevance'), time: z.enum(['hour', 'day', 'week', 'month', 'year', 'all']).optional().default('all'), limit: z.number().min(1).max(100).optional().default(25).describe('Default 25, range (1-100). Override ONLY IF user requests.'), author: z.string().optional(), flair: z.string().optional(), });
- src/mcp-server.ts:113-116 (registration)Registration of the search_reddit tool in the MCP server toolDefinitions array, specifying name, description, and input schema.name: 'search_reddit', description: 'Search for posts across Reddit or specific subreddits. Returns matching posts with content and metadata.', inputSchema: zodToJsonSchema(searchRedditSchema) as any, readOnlyHint: true
- src/mcp-server.ts:156-159 (registration)Dispatch case in the tools/call handler that routes search_reddit calls to the searchReddit method.case 'search_reddit': result = await tools.searchReddit( searchRedditSchema.parse(args) );