# reddit-readonly-mcp

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

> [!IMPORTANT]
> This project does not bypass Reddit access controls. Obtain explicit Reddit
> approval and OAuth credentials before using it. It provides no anonymous
> scraping or unauthenticated JSON fallback.

## 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.

## Tools

| Tool | Purpose |
| --- | --- |
| `list_subreddit` | List hot, new, rising, top, or controversial posts from one public subreddit. |
| `search_posts` | Search public posts inside one public subreddit. |
| `get_post` | Retrieve one public post from a Reddit permalink. |
| `get_comments` | Retrieve a bounded public comment tree from a Reddit permalink. |

## Configuration

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

| Variable | Required | Notes |
| --- | --- | --- |
| `REDDIT_CLIENT_ID` | Yes | Approved OAuth client ID. |
| `REDDIT_CLIENT_SECRET` | Yes | Approved OAuth client secret. |
| `REDDIT_USERNAME` | Yes | Used in Reddit's required descriptive User-Agent. |
| `REDDIT_ALLOWED_SUBREDDITS` | No | `*` by default, or a comma-separated allowlist. |
| `REDDIT_CACHE_TTL_SECONDS` | No | Defaults to 900; capped at 3600. |
| `REDDIT_REQUEST_INTERVAL_MS` | No | Defaults to 1100; cannot be below 1000. |

## Install from source

```bash
npm ci
npm run check
npm run build
```

### Codex

```bash
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

```bash
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

```bash
docker build -t reddit-readonly-mcp .
docker run --rm -i \
  --env-file /path/to/private/reddit.env \
  reddit-readonly-mcp
```

## Development

```bash
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`](https://github.com/karanb192/reddit-mcp-buddy). This project
uses an independent implementation and deliberately omits anonymous access,
password grants, user analysis, and all write functionality.

## License

MIT