Skip to main content
Glama
Reddit MCP Server

Reddit MCP Server

by tandat8503

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

  1. Clone the repository:

    git clone <repository-url>
    cd mcp-reddit
  2. Install dependencies:

    npm install
  3. Build the project:

    npm run build
  4. Start 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=30

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

  1. Start MCP Inspector:

   npx @modelcontextprotocol/inspector node dist/index.js
  1. Open browser: http://localhost:6274

  2. Test tools: Use the comprehensive test data in test-data.json

Quick Start Testing

All tools work immediately without any setup:

  1. get_subreddit_posts - Get posts from any subreddit

  2. search_reddit - Search across Reddit or specific subreddits

  3. get_user_profile - Get user profile information

  4. get_subreddit_info - Get subreddit details

  5. get_post_comments - Get comments for any post

  6. get_trending_subreddits - Get trending subreddits

  7. get_cross_posts - Find crossposts of a post

🎯 Available Tools

πŸ“– Read-Only Tools (7 tools - No Authentication Required)

  1. get_subreddit_posts - Get posts from a subreddit with sorting options

  2. search_reddit - Search for posts across Reddit or within specific subreddits

  3. get_user_profile - Get detailed profile information for any Reddit user

  4. get_subreddit_info - Get comprehensive subreddit information

  5. get_post_comments - Get comments for a specific post with sorting

  6. get_trending_subreddits - Get trending and popular subreddits

  7. get_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"
  }
}
{
  "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 build

Step 2: Start MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

Step 3: Open Browser

Navigate to http://localhost:6274

Step 4: Test All Tools

All tools work immediately without any setup:

  1. get_trending_subreddits - See what's popular on Reddit

  2. get_subreddit_info - Get details about any subreddit

  3. get_subreddit_posts - Browse posts from any subreddit

  4. search_reddit - Search for content across Reddit

  5. get_user_profile - Get information about any Reddit user

  6. get_post_comments - Read comments on any post

  7. get_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 and X-Ratelimit-Reset headers

  • Smart Warnings: Logs warnings when approaching rate limits

  • Graceful Handling: Returns helpful error messages when rate limits are exceeded

🚨 Troubleshooting

Common Issues

  1. 403 Forbidden

    • Check User-Agent string format in .env file

    • Ensure User-Agent follows Reddit's guidelines

    • Verify app is not suspended on Reddit

  2. 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

  3. 404 Not Found

    • Verify subreddit name is correct (without r/ prefix)

    • Check if post ID is valid

    • Ensure username exists on Reddit

Debug Steps

  1. Test with MCP Inspector:

    npx @modelcontextprotocol/inspector node dist/index.js
  2. Verify Environment (optional):

    cat .env
  3. Test All Tools:

    • Start with get_trending_subreddits to verify basic connectivity

    • Try 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 checking

  • Consistent Patterns: Unified createToolHandler wrapper eliminates boilerplate try-catch blocks

  • Magic 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

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Add tests if applicable

  5. Submit a pull request

πŸ“„ License

This project is licensed under the MIT License.

Available Tools

7 tools
get_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_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

    A4.2/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Provides 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.
      9
      1
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      Enables 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.
      17
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
      -