reddit-readonly-mcp

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

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

Configuration

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

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