Reddit MCP Server
Provides read-only access to search for posts within specific subreddits, allowing users to find content with various sorting options including relevance, hot, top, new, and comments.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Reddit MCP Server Search for top posts about 'OpenAI' in the artificial subreddit"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Reddit MCP Server
This MCP server allows Clients to interact with Reddit using OAuth2 authentication, enabling read-only access to search for posts within subreddits.
Features
Search posts: Search for posts within specific subreddits with various sorting options (relevance, hot, top, new, comments)
OAuth2 authentication: Secure authentication using Reddit's OAuth2 client credentials flow
Read-only access: Safe, read-only access to Reddit data without requiring user credentials
Related MCP server: Reddit MCP Server
Quick Start
Create a Reddit application to get your API credentials:
Click "Create App" or "Create Another App"
Choose "script" as the app type
Note down your client ID and client secret
Add this configuration to your Claude Desktop config file:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"reddit-mcp": {
"command": "npx",
"args": ["-y", "@enisze/reddit-mcp"],
"env": {
"REDDIT_CLIENT_ID": "your_client_id_here",
"REDDIT_CLIENT_SECRET": "your_client_secret_here",
"REDDIT_USER_AGENT": "reddit-mcp-server/1.0.0"
}
}
}
}Restart Claude Desktop
That's it! Claude can now search Reddit through the search_posts tool.
Example Usage
Try asking Claude:
"Can you search for posts about 'artificial intelligence' in the MachineLearning subreddit?"
"Search for the top 10 posts about 'Claude AI' in the artificial subreddit"
"Find recent discussions about 'programming best practices' in the programming subreddit"
Environment Variables
REDDIT_CLIENT_ID: Your Reddit app's client IDREDDIT_CLIENT_SECRET: Your Reddit app's client secretREDDIT_USER_AGENT: User agent string (optional, defaults to "reddit-mcp-server/1.0.0")
Development
If you want to contribute or run from source:
Clone the repository:
git clone <repository-url>
cd reddit-mcpInstall dependencies:
npm installBuild:
npm run buildRun:
npm startTest:
# Run unit tests (no API credentials needed)
npm test
# Run API integration tests (requires Reddit credentials)
npm run test:apiRunning Evaluations
To test the functionality of the Reddit MCP server:
npm run evalThis will run a series of evaluations to ensure all tools are working correctly.
Running Evals
The evals package loads an MCP client that then runs the index.ts file, so there is no need to rebuild between tests. You can load environment variables by prefixing the npx command. Full documentation can be found here.
OPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/index.tsDocker Support
You can also run this MCP server using Docker:
# Build the Docker image
docker build -t reddit-mcp .
# Run the container with environment variables
docker run -e REDDIT_CLIENT_ID=your_client_id \
-e REDDIT_CLIENT_SECRET=your_client_secret \
reddit-mcpAPI Documentation
search_posts
Searches for posts in a Reddit subreddit using OAuth2 authentication.
Parameters:
query(string, required): Search querysubreddit(string, required): The subreddit name (without r/ prefix)count(number, optional): Number of posts to return (1-100, default: 25)sort(string, optional): Sort order - 'relevance', 'hot', 'top', 'new', 'comments' (default: 'relevance')
Troubleshooting
Authentication Issues
Make sure your Reddit client ID and secret are correct
Ensure your Reddit app is configured as a "script" type
Check that your user agent string is descriptive and unique
Rate Limiting
The server implements basic rate limiting (2 seconds between requests)
Reddit has its own rate limits - if you hit them, wait before retrying
Common Errors
"Subreddit not found": Check the subreddit name spelling
"OAuth2 authentication failed": Verify your Reddit app credentials
"Invalid credentials": Make sure your client ID and secret are correct
Testing
The project includes comprehensive tests to verify functionality:
Unit Tests
Run basic functionality tests without requiring Reddit API credentials:
npm testThese tests verify:
Response formatting
Type definitions
Data structure handling
Error handling logic
API Integration Tests
Test actual Reddit API functionality (requires credentials):
npm run test:apiSet up your credentials in .env first (copy from .env.example).
These tests verify:
OAuth2 authentication flow
Search functionality
API response handling
Error handling for various scenarios
See TEST.md for detailed testing instructions.
License
MIT
Available Tools
1 toolsearch_postsB
Search for posts in a Reddit subreddit
Inputs: query (required), subreddit (required), count, sort.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
With only one tool, there is no possibility of confusion between tools. The tool's purpose is clear and distinct.
A single tool inherently has consistent naming since there are no other tools to compare against.
One tool for a Reddit server is severely inadequate. Reddit functionality typically requires multiple tools for different resources (posts, comments, subreddits, users).
The server is missing essential operations for Reddit, such as retrieving posts, managing comments, or interacting with subreddits. It only supports searching, leaving obvious gaps.
Related MCP Connectors
Query Reddit communities, posts, brands and trends from your AI agent. OAuth 2.1.
Search public Reddit posts, browse subreddit feeds, and read posts, comments, and profiles.
Read-only Reddit search API for AI agents: posts, comments, comment trees, subreddit rules.
Search, monitor and measure Reddit posts and comments. Previews work with no API key.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables browsing and searching Reddit content through read-only tools that access Reddit's official API. Supports searching posts, retrieving subreddit information, fetching hot posts, and getting detailed post information.54MIT
- FlicenseNot gradedqualityDmaintenanceProvides AI assistants with read-only access to Reddit's API for browsing subreddits, reading posts and comments, searching Reddit, and retrieving user/subreddit information. Enables safe exploration of Reddit content without posting capabilities through natural language interactions.-
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to interact with Reddit by searching subreddits, retrieving hot posts, and fetching detailed post information with comments through the Reddit API.-
- FlicenseNot gradedqualityCmaintenanceEnables interaction with Reddit through the Reddit API, allowing users to search posts, retrieve saved content, fetch comments, reply to comments, and access detailed post information with comment trees.4-