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.

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