reddit-mcp

A read-only Model Context Protocol server that wraps the Reddit API for subreddit browsing, in-subreddit search, comment-tree retrieval, and user-activity lookup. Intended for personal use tracking r/homelabsales, r/hardwareswap, and similar subreddits via Claude Code and Claude Desktop. Written in Python, runs locally over stdio.

Auth tiers (all optional)

The server auto-detects which of three tiers to use from which env vars you set:

Tier	Rate limit	Env vars	Notes
Anonymous	10 rpm	REDDIT_USER_AGENT (recommended)	Works with no setup; uses public .json endpoints.
App-only OAuth	60 rpm	Above + REDDIT_CLIENT_ID + REDDIT_CLIENT_SECRET	Requires a Reddit app.
Authenticated	100 rpm	Above + REDDIT_USERNAME + REDDIT_PASSWORD	Password grant; stores password in plaintext config.

New users: start with anonymous. Reddit ended self-service API key creation in November 2025 (Responsible Builder Policy), so obtaining OAuth credentials now requires an approval gate that usually declines personal scripts. Anonymous covers every read path this server implements. See docs/design.md section 3.2 for the full story.

Plugin install (local dev)

The whole repo is a Claude Code plugin (skill + slash commands + MCP server bundled). To try it locally:

cd /Users/conrad/Ai/reddit_mcp
uv pip install -e .                                          # one-time, sets up the MCP server in a venv
claude plugin marketplace add /Users/conrad/Ai/reddit_mcp    # register this repo as a local marketplace
claude plugin install reddit-deal-hunter@reddit-mcp-local    # install + enable the plugin

Restart Claude Code. On first MCP activation you will be prompted for five fields (reddit_user_agent, reddit_client_id, reddit_client_secret, reddit_username, reddit_password), all optional. Leave any or all blank to stay on a lower tier. Setting reddit_user_agent is recommended regardless of tier; use the format macos:reddit-mcp:0.2 (by /u/yourusername).

Once activated, the skill, commands /reddit-deal-hunter:scan and /reddit-deal-hunter:thread-check, and all four MCP tools (get_subreddit_posts, search_subreddit, get_post_details, user_analysis) become available.

Heads-up: as of April 2026 the MCP layer of the plugin bundle may not attach tools to Claude Code sessions on every install (inline mcpServers in plugin.json is documented-as-supported but the GUI runtime behavior varies). If the skill and slash commands show up but the mcp__reddit_mcp__* tools do not, fall back to the MCP-only install path below. See docs/tool-ux-findings.md and HANDOFF.md (session 5 addendum) for detail.

Manual install (MCP only, no plugin) — currently the most reliable path

If you want only the MCP server (no skill, no slash commands), or if the plugin-layer install above does not attach the MCP tools to your session, register it with Claude Code at user scope directly:

cd /Users/conrad/Ai/reddit_mcp
uv venv --python 3.12
uv pip install -e .

# Anonymous (zero credentials):
claude mcp add reddit_mcp \
  --scope user \
  --env REDDIT_USER_AGENT="macos:reddit-mcp:0.2 (by /u/yourusername)" \
  -- uv run --directory /Users/conrad/Ai/reddit_mcp reddit-mcp

# OAuth app-only (add client creds):
claude mcp add reddit_mcp \
  --scope user \
  --env REDDIT_USER_AGENT="macos:reddit-mcp:0.2 (by /u/yourusername)" \
  --env REDDIT_CLIENT_ID=YOUR_REDDIT_CLIENT_ID \
  --env REDDIT_CLIENT_SECRET=YOUR_REDDIT_CLIENT_SECRET \
  -- uv run --directory /Users/conrad/Ai/reddit_mcp reddit-mcp

Verify with claude mcp list (expect reddit_mcp ✓ Connected) and restart Claude Code so the tools attach to new sessions.

See docs/design.md section 7 for Claude Desktop registration and other client wiring.

Repo layout

reddit-mcp/
├── .claude-plugin/
│   ├── plugin.json                 # plugin manifest + inline mcpServers block
│   └── marketplace.json            # single-plugin local-marketplace descriptor
├── CLAUDE.md                       # repo-specific working notes for Claude Code
├── commands/                       # user-invoked slash commands
│   ├── scan.md                     # /reddit-deal-hunter:scan <query>
│   └── thread-check.md             # /reddit-deal-hunter:thread-check <permalink-or-id>
├── docs/
│   ├── design.md                   # full design, the authoritative read
│   ├── supply-chain-baseline.md    # pinned-deps audit baseline
│   └── tool-ux-findings.md         # known issues surfaced by the live eval run
├── evals/
│   └── reddit_eval.xml             # 10 qa_pairs for mcp-builder evaluation
├── pyproject.toml                  # mcp, httpx (pinned)
├── reddit_mcp.py                   # the MCP server (uses mcp SDK FastMCP)
├── skills/
│   └── deal-hunter/SKILL.md        # model-invoked deal-watching heuristics
└── tests/test_smoke.py             # module import + tool registration

Status

Pre-v1. Anonymous tier works end to end with zero credentials (live-validated against Reddit; 10/10 eval-suite pass). OAuth upgrade paths work if you have credentials. Remaining v1 work: a tool-response-projection refactor tracked in docs/tool-ux-findings.md. Public release after v1 validates.

See docs/design.md for the full design and rationale, CLAUDE.md for the working-notes version, and HANDOFF.md for the session-to-session handoff.

License

MIT.