Local Reddit MCP

A local, single-user, read-only Reddit MCP (Model Context Protocol) server. It exposes five tools that retrieve public Reddit content through the official Reddit Data API with OAuth 2.0. Retrieved content is cached locally in SQLite with full-text search and TTL expiry.

Key properties

• Read-only: No write actions to Reddit. No scraping. Uses the official Reddit Data API.

• Local & single-user: Runs on your machine via stdio. No remote HTTP transport.

• Privacy-conscious: Secrets stored in OS-backed encrypted storage (Windows DPAPI). No secrets in logs, commits, or tool results. Cache is local and purgeable.

• Bounded: Every tool enforces input/output caps. No arbitrary URL fetching.

• Honest: Deleted, restricted, and NSFW content represented honestly. Every result carries provenance, timestamps, expiry, stale flag, and truncation markers.

• Secure: SSRF prevention via host allowlist. Rate-limit handling with backoff. Circuit breaker. Untrusted content marked.

Related MCP server: reddit-mcp

Tools

1. search_reddit — search public posts/subreddits by query with bounded pagination

2. get_post — retrieve a single post by ID or permalink

3. get_post_comments — retrieve comments for a post with bounded depth/count

4. get_subreddit_info — retrieve subreddit metadata

5. get_user_content — retrieve a user's public posts/comments with bounds

Prerequisites

• Node.js ≥ 22.9.0 (requires the built-in node:sqlite module and the --env-file-if-exists flag)

• A Reddit developer application (https://www.reddit.com/prefs/apps) with OAuth credentials

Quick start

npm install
cp .env.example .env    # then add your Reddit credentials
npm run build
npm run auth -- login   # complete OAuth in browser
npm run start           # start MCP stdio server

MCP client configuration

Add the server to your MCP client configuration, e.g.:

{
  "mcpServers": {
    "reddit": {
      "command": "node",
      "args": ["/path/to/RedditMCP/dist/index.js"],
      "env": {
        "REDDIT_CLIENT_ID": "your_client_id",
        "REDDIT_REDIRECT_URI": "http://127.0.0.1:8888/callback",
        "REDDIT_USER_AGENT": "RedditMCP/1.0 (by your_username)",
        "CACHE_DB_PATH": "./data/reddit-cache.db"
      }
    }
  }
}

Store REDDIT_CLIENT_SECRET in your MCP client's secure/secret mechanism rather than committing it or placing it in a shared config file.

Environment variables

Commands

The npm scripts load a local .env file automatically when run from the project directory.

Development

npm run quality       # format check, lint, typecheck, tests, audit
npm test              # unit + integration tests
npm run test:e2e      # end-to-end MCP tests (vitest.e2e.config.ts)
npm run format        # format sources
npm run lint          # eslint
npm run typecheck     # tsc --noEmit

CI (.github/workflows/ci.yml) runs format check, lint, typecheck, tests, build, e2e tests, and npm audit on push/PR to main/master.

Documentation

• docs/install.md — installation and MCP client setup

• docs/oauth-setup.md — OAuth app registration, scopes, and token storage

• docs/operations.md — operations, privacy, retention, and troubleshooting

• docs/decisions.md — design decisions

License

MIT