reddit-api-automation-mcp

Control your own Reddit account from the command line or from Claude.

It reads feeds, searches, opens threads with their full comment trees, looks up users, and writes: posts, replies, edits, deletes, votes, joining and leaving subreddits, and saving items. Every write is guarded: it can be previewed, it is spaced and capped, and it can require a local confirmation.

It runs four ways:

• reddit-cli, a command-line tool.

• An MCP server, reddit-api-automation-mcp, over stdio for Claude Desktop and Claude Code, or over HTTP behind a bearer token.

• A Docker image for the HTTP server.

• A Claude Desktop extension (.mcpb), built with npm run mcpb.

Three backends can carry the same 32 tools. The official Reddit API is preferred. Two experimental routes work through a dedicated, locally enrolled browser profile: request replay and the rendered Playwright UI. They are Windows local CLI/stdio features only; HTTP, Docker, and the extension remain API-only. See browser-mode.md.

The feature set is ported from jordanburke/reddit-mcp-server, karanb192/reddit-mcp-buddy, and adhikasp/mcp-reddit. See NOTICE.md.

Status. All code is tested offline; no Reddit API call, browser, Playwright install, or live account operation has been performed. The API route is the mature one. Replay and browser UI are implemented from inspected upstream evidence and synthetic fixtures, and every experimental row is still implemented-offline-tested, never live-verified. See docs/backend-coverage.md.

Quick start: official API

1. Get a Reddit app and its credentials. Follow docs/credentials.md. It has every step, every link, and what to do when self-service app creation is closed.

2. Install. Requires Node 22.12 or newer.

   npm install
   cp .env.example .env          # on Windows: copy .env.example .env

3. Fill in .env. At minimum REDDIT_CLIENT_ID and REDDIT_USERNAME. See docs/configuration.md.

4. Log in (default oauth mode). Approve in the browser and paste the address back:

   node --env-file-if-exists=.env src/cli.js login

5. Check it works:

   node --env-file-if-exists=.env src/cli.js test
   node --env-file-if-exists=.env src/cli.js whoami

6. Try a write safely. Preview first, then send it to a community you own:

   node --env-file-if-exists=.env src/cli.js post YOUR_TEST_SUB --title "Hello" --text "A test" --dry-run

Related MCP server: reddit-mcp

Quick start: experimental browser profile

Playwright is an optional peer, installed explicitly. Nothing installs it for you.

node src/cli.js profile add work --username your_username
node src/cli.js profile configure work --enable-backends api,replay,browser --preference api,replay,browser
node src/cli.js browser doctor
node src/cli.js browser setup --install-package --install-browser --yes
node src/cli.js browser login work
node src/cli.js profile default work
node src/cli.js feed node --limit 3 --backend browser

Read docs/browser-mode.md before enabling either experimental backend. None of these steps has been verified against a live Reddit account in this repository.

Documentation

What it does

Reading (no writes):

• Feeds in any sort (hot, new, top, rising, controversial), with paging and optional subreddit details.

• Subreddit info, rules, post flairs, and Reddit's popular subreddits.

• Search across Reddit or inside a subreddit, filtered by author or flair.

• A post with its comment tree, and "load more" expansion for collapsed branches. Accepts a post ID, a fullname, or a reddit.com link.

• A user's karma and account details, their posts and comments, and a summary of where they are active.

• Your own overview, your saved items, and the subreddits you have joined.

• A public RSS fallback that needs no Reddit app (read-only, no scores).

• A glossary of Reddit terms (karma, AMA, ELI5, and more). Works offline.

Writing (every write is guarded):

• Create text or link posts; reply to posts and comments; edit and delete your own posts and comments.

• Vote (up, down, or clear), join and leave subreddits, save and unsave.

• --dry-run for previews, 2 seconds between writes (5 in strict mode), an hourly cap (30, or 10 in strict mode), and a 24-hour block on identical text.

• Application-level confirmations default off for all 11 write tools, including deletes. A profile can require a global or per-tool trusted local approval; confirm: true is optional evidence and never a substitute for that approval. Host permission prompts are separate.

• An optional bot disclosure footer on posts, comments, and edits.

Connecting to Claude: 32 MCP tools (21 read, 11 write) plus 11 local profile/browser helpers over stdio. HTTP exposes exactly the 32 Reddit tools. See docs/mcp.md.

Least privilege: login requests nine scopes, each tied to a feature. reddit-cli scopes shows all of Reddit's scopes this project knows about, with the reason each one is left out. See docs/security.md.

Auth modes at a glance

Details: docs/configuration.md and docs/how-it-works.md.

Backends at a glance

Backend fallback is only for an unsupported or pre-dispatch-unavailable implementation, never for an auth denial, throttle, challenge, or unknown write. The selection is frozen per call. See docs/browser-mode.md.

Status and limits

• Tested offline: the full suite runs with a fake fetch, fake Playwright/session, fake keyring, spawned stdio server, real HTTP server on an ephemeral port, and temporary REDDIT_CLI_HOME directories. Nothing contacts Reddit.

• Not tested live: no Reddit API call, browser launch, Playwright install, keyring operation, or account experiment has been performed. Replay and browser coverage rows stay unverified.

• Browser gaps: get_post_flairs is unsupported on both experimental backends; the browser also cannot implement get_more_comments; UI paging is not an API cursor and its continuation resume is not implemented. See docs/backend-coverage.md.

• Distributions: HTTP, Docker, and the .mcpb extension are API-only. The extension excludes the CLI and the browser/replay modules by construction.

• Docker: the image builds, and the HTTP endpoint was checked in a running container (401 without the token, a successful initialize with it).

• Extension: builds on Windows, validates, unpacks, and serves its 32 tools over stdio. It has not been installed in Claude Desktop, and it is not signed.

• Platform: the keychain library is native, so an extension bundle works only on the operating system it was built on. Browser backends target Windows local CLI/stdio first.

• Scope changes need a new login.

• Not supported: moderation tools, direct messages, reports, Reddit chat, and Reddit Answers.

• Reddit's API policy is changing. Read docs/credentials.md before you build on it.

License and credits

This project is licensed under the Apache License 2.0. See LICENSE.

The code in this repository is written from scratch. The feature set, endpoint choices, and several behaviors are credited in NOTICE.md.