Skip to main content
Glama
reddit-readonly-mcp

reddit-readonly-mcp

by MufanQiu

reddit-readonly-mcp

A small, policy-conscious Model Context Protocol (MCP) server for approved, read-only access to public Reddit discussions.

IMPORTANT

This project does not bypass Reddit access controls. Obtain explicit Reddit approval and OAuth credentials before using it. It provides no anonymous scraping or unauthenticated JSON fallback.

Design

  • Four read-only tools: list posts, search within one community, get a post, and get its comments.

  • App-only OAuth authentication against Reddit's official API.

  • Access to publicly viewable subreddits, with an optional operator allowlist and conservative result and comment limits.

  • Serialized requests with a configurable minimum interval.

  • A bounded in-memory cache with a hard one-hour maximum lifetime.

  • No write operations, user-history tools, telemetry, persistent database, or recovery of removed content.

Related MCP server: Reddit MCP Tool

Tools

Tool

Purpose

list_subreddit

List hot, new, rising, top, or controversial posts from one public subreddit.

search_posts

Search public posts inside one public subreddit.

get_post

Retrieve one public post from a Reddit permalink.

get_comments

Retrieve a bounded public comment tree from a Reddit permalink.

Configuration

Copy .env.example into your secret manager or MCP client configuration. Do not commit an .env file.

Variable

Required

Notes

REDDIT_CLIENT_ID

Yes

Approved OAuth client ID.

REDDIT_CLIENT_SECRET

Yes

Approved OAuth client secret.

REDDIT_USERNAME

Yes

Used in Reddit's required descriptive User-Agent.

REDDIT_ALLOWED_SUBREDDITS

No

* by default, or a comma-separated allowlist.

REDDIT_CACHE_TTL_SECONDS

No

Defaults to 900; capped at 3600.

REDDIT_REQUEST_INTERVAL_MS

No

Defaults to 1100; cannot be below 1000.

Install from source

npm ci
npm run check
npm run build

Codex

codex mcp add reddit-readonly \
  --env REDDIT_CLIENT_ID=... \
  --env REDDIT_CLIENT_SECRET=... \
  --env REDDIT_USERNAME=... \
  --env REDDIT_ALLOWED_SUBREDDITS='*' \
  -- node /absolute/path/to/reddit-readonly-mcp/dist/index.js

Claude Code

claude mcp add --transport stdio reddit-readonly -s user \
  --env REDDIT_CLIENT_ID=... \
  --env REDDIT_CLIENT_SECRET=... \
  --env REDDIT_USERNAME=... \
  --env REDDIT_ALLOWED_SUBREDDITS='*' \
  -- node /absolute/path/to/reddit-readonly-mcp/dist/index.js

Docker

docker build -t reddit-readonly-mcp .
docker run --rm -i \
  --env-file /path/to/private/reddit.env \
  reddit-readonly-mcp

Development

npm run typecheck
npm test
npm run build

Network integration tests are intentionally absent until approved Reddit credentials are available. Unit tests cover policy boundaries such as URL parsing, optional allowlists, cache limits, and response shaping.

Prior art

The tool naming and local MCP ergonomics were informed by the MIT-licensed reddit-mcp-buddy. This project uses an independent implementation and deliberately omits anonymous access, password grants, user analysis, and all write functionality.

License

MIT

Available Tools

4 tools
get_commentsB

Get a bounded public comment tree from an approved Reddit permalink.

Inputs: post_url (required), sort, depth, limit.

get_postA

Get one public post from an approved Reddit permalink.

Inputs: post_url (required).

list_subredditC

List public posts from one approved subreddit.

Inputs: subreddit (required), sort, limit, time_filter.

search_postsC

Search public posts inside one approved subreddit.

Inputs: query (required), subreddit (required), sort, limit, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: listing subreddit posts, searching posts, fetching a single post, and fetching comments. No two tools overlap in function, and the descriptions make the boundaries unambiguous.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern: list_subreddit, search_posts, get_post, get_comments. While nouns are singular or plural, the pattern is uniform across the set.

    Tool Count5/5

    4 tools is well-scoped for a read-only Reddit interface, covering the essential browsing actions without unnecessary bloat. The count fits perfectly within the typical range for a focused server.

    Completeness4/5

    The core read-only workflows are covered: list, search, get post, and get comments. Minor gaps exist, such as no subreddit metadata or user post retrieval, but these are not critical for the stated purpose of browsing public posts and comments.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    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
      A
      quality
      D
      maintenance
      Enables 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.
      5
      4
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      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.
      7
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides 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.
      -