English | 简体中文

reddit-readonly-mcp

An unofficial Model Context Protocol (MCP) server designed to fetch public Reddit content reliably from datacenter and VPS IPs without any Reddit API credentials or user accounts.

By emulating Reddit's official Android application token exchange (based on the technique from redlib), reddit-readonly-mcp acquires anonymous application-only tokens to query oauth.reddit.com directly with high resilience.

✨ Features

• 🔑 Zero Credentials Required: No Reddit Developer app approval, API secrets, or account credentials required.

• 🌐 VPS & Datacenter Friendly: Listings, subreddit metadata, user feeds and single posts keep working from cloud IPs, where Reddit's anonymous JSON endpoints return 403.

• 💬 GraphQL for comments, search and profiles: Reddit closed the anonymous REST comment, search and profile endpoints in October 2026, so those tools use the persisted operations the official Android app calls on gql-fed.reddit.com.

• 🛡️ Strictly Read-Only & Privacy-First: Queries public data exclusively; contains zero write paths or credential-handling logic.

• 🔄 3-Tier Resilient Fallback: Automatic cascade: Mobile Token → Installed Client Token → RSS Fallback.

• ⚡ Smart Rate-Limit & Token Rollover: Proactively rotates tokens when remaining requests drop to $\le 5$, handles 429 backoff gracefully, and caches responses via an in-memory LRU cache.

• 🔌 Dual Transports: Ready for both stdio (local MCP clients like Claude Desktop, Cursor, Hermes) and streamable HTTP (remote/container environments).

Upstream status (November 2026). Reddit is moving to a logged-in-only experience (announcement, Q3'26 shareholder letter). Anonymous tokens can still read listings, subreddit metadata, user feeds and single posts (via /by_id); comments, search and user profiles are served by the GraphQL channel described below instead of the REST endpoints, which now answer HTTP 403. The GraphQL persisted-query hashes are an external dependency that Reddit can change at any time, so treat this as a moving target.

Related MCP server: Reddit Buddy MCP

🚀 Quick Start

Prerequisites

• Node.js $\ge 20$

1. Run it

Published on npm as reddit-readonly-mcp:

npx -y reddit-readonly-mcp          # stdio, what MCP clients launch

Or install it globally:

npm i -g reddit-readonly-mcp
reddit-readonly-mcp

Or run the latest main from the Gitea repository:

npx --allow-git=all -y "git+https://git.nite07.com/nite/reddit-readonly-mcp.git"

2. Configure Your MCP Client

Standard MCP Client Configuration (stdio)

Add this to your MCP configuration file (e.g. claude_desktop_config.json or Cursor mcp.json):

{
  "mcpServers": {
    "reddit": {
      "command": "npx",
      "args": ["-y", "reddit-readonly-mcp"]
    }
  }
}

Hermes Agent (~/.hermes/config.yaml)

mcp_servers:
  reddit:
    command: npx
    args:
      - "-y"
      - reddit-readonly-mcp

Streamable HTTP Mode

For Docker, MetaMCP, or remote gateway deployments:

npx -y reddit-readonly-mcp --http --port 3000 --host 127.0.0.1

• Endpoint: http://127.0.0.1:3000/mcp

• Health check: GET http://127.0.0.1:3000/health

• Note: The HTTP server binds to 127.0.0.1 by default and enforces Host-header validation to prevent DNS rebinding. It has no built-in authentication; place it behind a secure proxy if exposing externally.

3. From Source (development)

git clone https://git.nite07.com/nite/reddit-readonly-mcp.git
cd reddit-readonly-mcp
npm install && npm run build
node dist/cli.js

The compiled entry point is dist/cli.js.

🛠️ Available Tools

The server provides 12 strictly read-only tools (annotated with readOnlyHint: true). Output fields are sanitized and trimmed (id, title, author, subreddit, score, created timestamp, permalink, truncated selftext/body) instead of returning raw Reddit JSON dumps.

Posts & Feeds

Comments & Discussions

How comments are fetched (October 2026 change). Reddit now answers the anonymous REST comment endpoints (/r/<sub>/comments/..., /comments/..., /api/info, /api/morechildren) with an HTML 403 page, and the %2F path-encoding workaround that redlib shipped in v0.40.0 stopped working within two weeks. This server therefore reads comments through the same persisted GraphQL operation the official Android client uses (POST https://gql-fed.reddit.com/, operationName: PostComments), with the same anonymous token and device headers. A single request returns at most 200 comments; pass the returned after cursor to page through top-level comments and raise limit/depth to see more replies. Collapsed branches are still listed as more stubs (parent_id, count) and cannot be expanded individually.

Search

Community & Users

Diagnostics

⚙️ Architecture & Fallback Cascade

reddit-readonly-mcp utilizes a multi-tiered failover pipeline to maintain high availability:

[Request]
   │
   ▼
1. Mobile OAuth Token ──── (5 consecutive failures) ───► 2. Installed Client Grant
   │ (Default: auth/v2/oauth/access-token/loid)                 │
   │                                                            ▼ (5 consecutive failures)
   └─────────────────────────────────────────────────────► 3. Public RSS Fallback
                                                                (browse_subreddit & get_top_posts)

1. Mobile Token (mobile): Emulates Reddit's Android application handshake with random real device characteristics, acquiring a 24-hour bearer token.

2. Installed Client Token (installed): Automatically activates if the mobile token endpoint experiences 5 consecutive failures.

3. RSS Fallback (rss): Emergency read-only mode for feeds (browse_subreddit and get_top_posts) if OAuth endpoints are unreachable.

4. Auto-Recovery: The server checks primary backends every 30 minutes and automatically restores higher-tier access once available.

GraphQL channel (comments, search, profiles)

Reddit closed the anonymous REST comment, search and profile endpoints in October 2026, so those three tools talk to POST https://gql-fed.reddit.com/ with the Android app's persisted operations:

They reuse the same anonymous token, device headers and rate-limit handling: on 401 the token is refreshed once, on 429 it is rolled over and the request retried once, and identical requests are cached. Responses are converted back into Reddit's JSON shapes before trimming, so the tool output format is unchanged; doctor reports the channel under graphql_backend. The persisted-query hashes come from Amqx/reddit-gql and are an external dependency.

Token & Rate-Limit Management

• Proactive Token Refresh: Automatically renews the OAuth token 2 minutes prior to expiration.

• Quota Rollover: Monitors x-ratelimit-remaining; rolls over to a clean token window when remaining requests drop to $\le 5$.

• Backoff & Retries: Handles HTTP 429 by triggering token rollover followed by exponential retry respecting Retry-After.

• In-Memory Cache: Bounded LRU cache reduces redundant upstream calls.

🔧 Environment Variables

All configuration is optional. No credential variables (client secret, password, etc.) exist or are accepted.

📋 Scope & Design Boundaries

• Read-Only by Design: Write actions (submitting posts, comments, voting, private messages) are intentionally excluded. They require user-specific OAuth scopes and accounts, which are out of scope.

• Public Data Only: Private subreddits, banned users, and authenticated user endpoints (e.g. saved items, inbox) are not accessible.

• Comments, search and profiles depend on internal endpoints: those three tools use the Android app's GraphQL persisted operations, which are not a documented public API. If Reddit changes a query hash or starts requiring a session there, the affected tool fails with a clear error instead of silently falling back to a blocked REST route.

• Known anonymous refusals (November 2026): the REST comment endpoints, /search and /user/<name>/about return HTTP 403 to anonymous tokens; the server routes those features through GraphQL instead. The GraphQL profile channel exposes total karma only (no post/comment split and no account flags).

🧪 Development & Testing

# Build TypeScript to dist/
npm run build

# Type check
npm run typecheck

# Unit tests (mocked, offline)
npm test

# Protocol wire verification (stdio & HTTP check)
npm run wire

# Live integration test against real Reddit endpoints
npm run smoke

As of November 2026 the live smoke test passes against real Reddit: all 12 tools, including search_reddit, get_user_info and get_post_comments, go through the GraphQL channel where the REST endpoints are refused.

📄 License

MIT.

Credits

• Android device metadata in src/auth/android-app-versions.ts is sourced from redlib (MIT).

• The GraphQL persisted-operation names, sha256 hashes and variable shapes used for comments, search and user profiles (PostComments, SearchPosts, SearchCommunities, SearchPeople, ProfileDetailsByName) were taken from Amqx/reddit-gql (GPL-3.0). Only those protocol identifiers and observed variable shapes are used; no code from that project is copied into this repository.