Provides comprehensive Reddit API access with 13 tools covering both read-only operations (getting posts, comments, user profiles, subreddit info, search) and authenticated actions (voting, commenting, creating posts) through OAuth2 authentication.
MCP Reddit Server
A Model Context Protocol (MCP) server that provides read-only access to Reddit's API through a standardized interface. This server focuses on content discovery and analysis without requiring OAuth authentication.
🚀 Features
7 Read-Only Tools: Comprehensive Reddit content access without authentication
No OAuth Required: Works immediately without any setup or configuration
Type-Safe Architecture: Full TypeScript with Zod schema validation and z.infer types
Error Handling: Robust error handling with dynamic troubleshooting tips
Clean Code Patterns: Consistent tool handlers with reduced boilerplate
MCP Standard: Compliant with Model Context Protocol specifications
Smart Defaults: Intelligent parameter defaults for better user experience
🔐 No Authentication Required
This server provides read-only access to Reddit's public API without requiring any authentication. All tools work immediately without OAuth setup or API credentials.
Reddit API Access
The server uses Reddit's public API endpoints that don't require authentication:
Public Posts: Access to all public subreddit posts
Public Comments: Access to all public comments
Public Profiles: Access to public user information
Public Subreddits: Access to subreddit information and metadata
🛠️ Installation
Clone the repository:
git clone <repository-url> cd mcp-redditInstall dependencies:
npm installBuild the project:
npm run buildStart the server:
npm start
⚙️ Configuration
No configuration required! The server works immediately without any setup.
Optional Environment Variables
You can create a .env
file for optional configuration:
User-Agent String
While not required, it's recommended to set a custom User-Agent string to identify your application:
Format:
AppName/Version (by /u/YourUsername)
Example:
MCP-Reddit-Server/1.0.0 (by /u/YourUsername)
🧪 Testing
Using MCP Inspector
Start MCP Inspector:
Open browser: http://localhost:6274
Test tools: Use the comprehensive test data in
test-data.json
Quick Start Testing
All tools work immediately without any setup:
get_subreddit_posts
- Get posts from any subredditsearch_reddit
- Search across Reddit or specific subredditsget_user_profile
- Get user profile informationget_subreddit_info
- Get subreddit detailsget_post_comments
- Get comments for any postget_trending_subreddits
- Get trending subredditsget_cross_posts
- Find crossposts of a post
🎯 Available Tools
📖 Read-Only Tools (7 tools - No Authentication Required)
get_subreddit_posts
- Get posts from a subreddit with sorting optionssearch_reddit
- Search for posts across Reddit or within specific subredditsget_user_profile
- Get detailed profile information for any Reddit userget_subreddit_info
- Get comprehensive subreddit informationget_post_comments
- Get comments for a specific post with sortingget_trending_subreddits
- Get trending and popular subredditsget_cross_posts
- Find crossposts of a specific post
📖 Tool Usage Examples
Read-Only Tools (No Authentication Required)
Get Subreddit Posts
Search Reddit
Get User Profile
Get Subreddit Info
Get Post Comments
Get Trending Subreddits
Get Cross Posts
🔧 Tool Features
Smart Defaults: Intelligent parameter defaults for better UX
Type Safety: Full TypeScript validation with Zod schemas
Error Handling: Comprehensive error messages with troubleshooting tips
Rate Limiting: Built-in protection against API rate limits
Inline Documentation: Detailed descriptions with examples for each tool
🚀 Getting Started Workflow
Step 1: Setup and Build
Step 2: Start MCP Inspector
Step 3: Open Browser
Navigate to http://localhost:6274
Step 4: Test All Tools
All tools work immediately without any setup:
get_trending_subreddits
- See what's popular on Redditget_subreddit_info
- Get details about any subredditget_subreddit_posts
- Browse posts from any subredditsearch_reddit
- Search for content across Redditget_user_profile
- Get information about any Reddit userget_post_comments
- Read comments on any postget_cross_posts
- Find crossposts of any post
📊 Rate Limiting
Rate Limits
Public API: 60 requests per minute (Reddit default)
Built-in Protection: Server includes rate limiting to prevent API abuse
Header Monitoring: Automatically reads
X-Ratelimit-Remaining
andX-Ratelimit-Reset
headersSmart Warnings: Logs warnings when approaching rate limits
Graceful Handling: Returns helpful error messages when rate limits are exceeded
🚨 Troubleshooting
Common Issues
403 Forbidden
Check User-Agent string format in
.env
fileEnsure User-Agent follows Reddit's guidelines
Verify app is not suspended on Reddit
Rate Limit Exceeded
Server automatically monitors rate limits
Check console for rate limit warnings
Wait for the reset time shown in error messages
Consider implementing request queuing for high-volume usage
404 Not Found
Verify subreddit name is correct (without r/ prefix)
Check if post ID is valid
Ensure username exists on Reddit
Debug Steps
Test with MCP Inspector:
npx @modelcontextprotocol/inspector node dist/index.jsVerify Environment (optional):
cat .envTest All Tools:
Start with
get_trending_subreddits
to verify basic connectivityTry
get_subreddit_posts
with popular subreddits like "programming"Use
search_reddit
to test search functionality
🏗️ Technical Improvements
Code Quality Enhancements
Type Safety: All tools now use
z.infer<typeof Schema>
for compile-time type checkingConsistent Patterns: Unified
createToolHandler
wrapper eliminates boilerplate try-catch blocksMagic Number Constants: Replaced hardcoded values with named constants for better maintainability
Error Handling: Dynamic error messages with context-specific troubleshooting tips
Architecture Improvements
Rate Limit Intelligence: Real-time monitoring of Reddit API rate limit headers
Smart Defaults: Intelligent parameter defaults based on tool context
Clean Code: Consistent patterns and reduced boilerplate
Developer Experience
Inline Documentation: Comprehensive tool descriptions with examples and usage patterns
TypeScript Strict Mode: Full type safety with strict TypeScript configuration
Consistent Error Responses: Standardized error format across all tools
Build Validation: Automated TypeScript compilation with error checking
📁 Project Structure
🤝 Contributing
Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request
📄 License
This project is licensed under the MIT License.
🔗 Links
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables interaction with Reddit through a comprehensive API interface supporting both read-only operations (browsing posts, comments, user profiles) and authenticated actions (posting, commenting, voting) via OAuth2 authentication.
Related MCP Servers
- AsecurityAlicenseAqualityA server allowing interaction with Reddit via the public API, enabling browsing frontpage posts, retrieving subreddit details, and reading post comments through a Model Context Protocol.Last updated -8101MIT License
- -securityAlicense-qualityEnables interaction with GitHub repositories through the GitHub API, allowing file operations, repository management, issue tracking, and code search through natural language commands.Last updated -32MIT License
- AsecurityFlicenseAqualityEnables users to interact with X (Twitter) through the X API. Supports posting tweets, retrieving user timelines, searching tweets, and replying to tweets with comprehensive error handling.Last updated -30
- -securityFlicense-qualityProvides access to Reddit's API for retrieving posts, comments, user information, and search functionality. Supports multiple authentication methods and comprehensive Reddit data operations including subreddit browsing, post retrieval, and user profile access.Last updated -45