reddit-readonly-mcp
Provides read-only access to public Reddit discussions, with tools to list posts, search within a subreddit, retrieve a specific post, and get its comment tree.
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-readonly-mcp list hot posts from AskReddit"
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-readonly-mcp
A small, policy-conscious Model Context Protocol (MCP) server for approved, read-only access to public Reddit discussions.
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 hot, new, rising, top, or controversial posts from one public subreddit. |
| Search public posts inside one public subreddit. |
| Retrieve one public post from a Reddit permalink. |
| 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 |
| Yes | Approved OAuth client ID. |
| Yes | Approved OAuth client secret. |
| Yes | Used in Reddit's required descriptive User-Agent. |
| No |
|
| No | Defaults to 900; capped at 3600. |
| No | Defaults to 1100; cannot be below 1000. |
Install from source
npm ci
npm run check
npm run buildCodex
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.jsClaude 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.jsDocker
docker build -t reddit-readonly-mcp .
docker run --rm -i \
--env-file /path/to/private/reddit.env \
reddit-readonly-mcpDevelopment
npm run typecheck
npm test
npm run buildNetwork 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 toolsget_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
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
Search public Reddit posts, browse subreddit feeds, and read posts, comments, and profiles.
Browse and manage Reddit posts, comments, and threads. Fetch user activity, explore hot/new/rising…
Read-only Reddit search API for AI agents: posts, comments, comment trees, subreddit rules.
Query Reddit communities, posts, brands and trends from your AI agent. OAuth 2.1.
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
- 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
- AlicenseAqualityDmaintenanceEnables 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.7MIT
- 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.-