Reddit MCP Server
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.
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 show me the top posts from r/technology today"
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.
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
Related MCP server: Reddit MCP Server
π 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:
# Optional: Custom User-Agent (recommended)
REDDIT_USER_AGENT=Your-App-Name/1.0.0 (by /u/YourUsername)
# Optional: Request timeout
TIMEOUT_SECONDS=30User-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:
npx @modelcontextprotocol/inspector node dist/index.jsOpen 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
{
"name": "get_subreddit_posts",
"arguments": {
"subreddit": "programming",
"sort": "hot"
}
}Search Reddit
{
"name": "search_reddit",
"arguments": {
"query": "python tutorial",
"subreddit": "learnprogramming"
}
}Get User Profile
{
"name": "get_user_profile",
"arguments": {
"username": "spez"
}
}Get Subreddit Info
{
"name": "get_subreddit_info",
"arguments": {
"subreddit": "programming"
}
}Get Post Comments
{
"name": "get_post_comments",
"arguments": {
"post_id": "1n1nlse",
"sort": "best"
}
}Get Trending Subreddits
{
"name": "get_trending_subreddits",
"arguments": {}
}Get Cross Posts
{
"name": "get_cross_posts",
"arguments": {
"post_id": "1n1nlse"
}
}π§ 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
npm install
npm run buildStep 2: Start MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.jsStep 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-RemainingandX-Ratelimit-ResetheadersSmart 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
.envfileEnsure 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_subredditsto verify basic connectivityTry
get_subreddit_postswith popular subreddits like "programming"Use
search_redditto 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
createToolHandlerwrapper 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
mcp-reddit/
βββ src/
β βββ services/
β β βββ reddit-api.ts # Reddit API service
β βββ types/
β β βββ index.ts # TypeScript types and Zod schemas
β βββ index.ts # Main MCP server with 7 read-only tools
βββ test-data.json # Comprehensive test data for all tools
βββ MCP_TEST_DATA.md # Detailed testing guide
βββ QUICK_START.md # Quick start guide
βββ .env # Optional environment variables
βββ env.example # Environment template
βββ README.md # This fileπ€ 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
Available Tools
7 toolsget_cross_postsA
π Find crossposts of a Reddit post π― What it does: Finds posts that were cross-posted from the original post π Required: post_id (Reddit post ID to find crossposts for) π‘ Examples: β’ Find crossposts: {"post_id": "1n1nlse"} β’ Check shares: {"post_id": "1abc123"} π Output: List of crossposts with title, author, subreddit, score, and Reddit link
Inputs: post_id (required).
get_post_commentsA
π¬ Get comments for a Reddit post π― What it does: Fetches comments and replies for any Reddit post π Required: post_id (Reddit post ID, found in post URLs) βοΈ Optional: sort ('best', 'top', 'new') π‘ Examples: β’ Get comments: {"post_id": "1n1nlse"} β’ Best comments: {"post_id": "1n1nlse", "sort": "best"} β’ New comments: {"post_id": "1n1nlse", "sort": "new"} π Output: Formatted comment tree with author, score, timestamp, and nested replies
Inputs: post_id (required), sort.
get_subreddit_infoA
π Get subreddit information π― What it does: Fetches detailed info about any Reddit subreddit π Required: subreddit name (without r/ prefix) π‘ Examples: β’ Get info: {"subreddit": "programming"} β’ Check subreddit: {"subreddit": "AskReddit"} β’ View details: {"subreddit": "MachineLearning"} π Output: Subreddit details with description, subscribers, active users, creation date, NSFW status, and URL
Inputs: subreddit (required).
get_subreddit_postsA
π Get posts from a subreddit π― What it does: Fetches posts from any Reddit subreddit with sorting options π Required: subreddit name (e.g., 'programming', 'AskReddit', 'MachineLearning') βοΈ Optional: sort ('hot', 'new', 'top') π‘ Examples: β’ Get hot posts: {"subreddit": "programming"} β’ Get new posts: {"subreddit": "AskReddit", "sort": "new"} β’ Get top posts: {"subreddit": "MachineLearning", "sort": "top"} π Output: Formatted list with title, author, score, comments, date, and Reddit link
Inputs: subreddit (required), sort.
get_trending_subredditsA
π₯ Get trending/popular subreddits π― What it does: Fetches list of currently popular and trending subreddits π Required: None (no parameters needed) π‘ Examples: β’ Get trending: {} β’ Simple call: {} π Output: List of trending subreddits with name, title, subscribers, description, and URL
Inputs: no named parameters.
get_user_profileA
π€ Get Reddit user profile information π― What it does: Fetches detailed profile info for any Reddit user π Required: username (Reddit username without u/ prefix) π‘ Examples: β’ Get profile: {"username": "spez"} β’ Check user: {"username": "AwkwardTension4482"} β’ View profile: {"username": "gallowboob"} π Output: User info with karma, account age, gold status, moderator status, and profile link
Inputs: username (required).
search_redditA
π Search Reddit posts and comments π― What it does: Searches across Reddit or within a specific subreddit π Required: query (search terms) βοΈ Optional: subreddit (limit search to specific subreddit) π‘ Examples: β’ Global search: {"query": "machine learning"} β’ Subreddit search: {"query": "python tutorial", "subreddit": "programming"} β’ Tech search: {"query": "TypeScript", "subreddit": "typescript"} π Output: Formatted search results with title, author, subreddit, score, and link
Inputs: query (required), subreddit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 7 tools
Each tool has a clearly distinct purpose targeting specific Reddit entities or actions: crossposts, post comments, subreddit info, subreddit posts, trending subreddits, user profiles, and search. There is no overlap in functionality, and the descriptions clearly differentiate what each tool does, making misselection unlikely.
All tool names follow a consistent verb_noun pattern using snake_case, starting with 'get_' for retrieval operations or 'search_' for search functionality. This uniformity makes the tool set predictable and easy to understand, with no deviations in naming conventions.
With 7 tools, the count is well-scoped for a Reddit server, covering core read-only operations like fetching posts, comments, subreddits, users, and search. Each tool serves a unique and necessary function without bloat, fitting typical expectations for such a domain.
The tool set provides comprehensive read-only coverage for browsing Reddit content, including posts, comments, subreddits, users, and search. A minor gap exists in write operations (e.g., posting, voting, commenting), but for a retrieval-focused server, the surface is nearly complete and supports common agent workflows without dead ends.
Related MCP Connectors
Browse and manage Reddit posts, comments, and threads. Fetch user activity, explore hot/new/risingβ¦
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.
Reddit: Reddit Data API offers streamlined access to Redditβs public data, like posts, comments.
Related MCP Servers
- AlicenseBqualityDmaintenanceProvides 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.91MIT
- AlicenseCqualityDmaintenanceEnables comprehensive Reddit interaction including fetching posts, analyzing users and subreddits, searching content, and creating posts/comments. Supports both read-only mode with client credentials and full functionality with user authentication.17MIT
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Reddit through a Reddable account, allowing users to fetch posts and comments, reply to discussions, and manage comment visibility using secure API key authentication.MIT
- 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-