# Reddit Search MCP Server

A small self-hosted server that lets Claude search Reddit directly from
chat. You host this; Claude's servers call it over HTTPS once you add it
as a custom connector.

No Anthropic API key required — this server only talks to Reddit via
PRAW. Claude is the *caller*, not the other way around.

## What it exposes

Two tools, callable from any Claude chat once connected:

- **search_reddit** — search by keyword, optional subreddit/sort/time
  filter, returns posts + their top comments.
- **get_reddit_thread** — fetch one specific thread by URL in more depth
  (useful as a follow-up after search_reddit).

## 1. Get Reddit API credentials

Reddit tightened this in 2026 — self-service app creation at
`reddit.com/prefs/apps` is no longer sufficient on its own for new
apps. You now need to request access first:

1. Submit Reddit's Data API access request (non-commercial):
   https://support.reddithelp.com/hc/en-us/requests/new?ticket_form_id=14868593862164
   Reddit's form will first point you to Devvit — that's for apps that
   *run inside Reddit* (bots, subreddit widgets, moderation tools).
   This server does the opposite: it's an external service that pulls
   Reddit search results out to be used elsewhere (in a Claude chat).
   Devvit has no general external query API for that, so this is the
   "my use case isn't supported by Devvit" case the form is filtering
   for — say so plainly in the ticket.
2. Describe the use case honestly: a personal, non-commercial Reddit
   search tool for your own use, low volume (well under the 100
   queries/minute free-tier cap).
3. Once approved, go to https://www.reddit.com/prefs/apps and create
   an app of type **script** — this is where you'll actually get the
   `client_id` (under the app name) and `client_secret` values.
4. Don't use Reddit's **Developer Platform** (developers.reddit.com /
   Devvit) — that's for apps that run inside Reddit itself (bots,
   subreddit tools), not for external read access like this server
   needs.

Approval isn't instant the way it used to be, so budget some lead time
before you can actually run this.

## 2. Configure

```bash
cp .env.example .env
# edit .env and fill in REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET,
# REDDIT_USER_AGENT, and a random MCP_AUTH_TOKEN
```

Generate a random token for `MCP_AUTH_TOKEN`, e.g.:
```bash
python3 -c "import secrets; print(secrets.token_urlsafe(32))"
```

## 3. Run it

### Locally (for testing)
```bash
pip install -r requirements.txt
export $(cat .env | xargs)   # or use python-dotenv / your shell's method
python server.py
```
It listens on `http://0.0.0.0:8000/mcp` by default.

### With Docker
```bash
docker build -t reddit-mcp-server .
docker run -p 8000:8000 --env-file .env reddit-mcp-server
```

## 4. Running on Unraid

### Option A — Compose Manager plugin (recommended)

1. In Community Applications, install **Compose Manager** (by dcflachs)
   if you don't have it already.
2. Create a new stack, e.g. `/mnt/user/appdata/reddit-mcp-server/`, and
   drop `docker-compose.yml`, `server.py`, `requirements.txt`,
   `Dockerfile`, and your filled-in `.env` (including `TUNNEL_TOKEN` —
   see step 5) in there.
3. In Compose Manager, point it at that folder and hit **Compose Up**.
   It'll build the `reddit-mcp-server` image locally and pull
   `cloudflared`, then start both.

### Option B — plain Docker via the Unraid terminal

```bash
cd /mnt/user/appdata/reddit-mcp-server
docker build -t reddit-mcp-server .
docker run -d --name reddit-mcp-server --restart unless-stopped \
  --env-file .env reddit-mcp-server
docker run -d --name reddit-mcp-cloudflared --restart unless-stopped \
  --env-file .env --link reddit-mcp-server cloudflare/cloudflared:latest tunnel run
```
(Compose is genuinely easier here since it wires the two containers'
internal networking together automatically — Option A is worth the
extra plugin.)

## 5. Expose it via Cloudflare Tunnel

Your NPM is internal-only, so it can't publish this to the internet —
Cloudflare Tunnel is the actual path here, not just an alternative.
Full walkthrough in **CLOUDFLARE_TUNNEL.md**, short version:

1. Cloudflare Zero Trust dashboard → Networks → Tunnels → create one
2. Add a public hostname pointing at `reddit-mcp-server:8000` (the
   Compose service name — cloudflared reaches it over the internal
   Compose network, no port mapping needed)
3. Copy the tunnel token into `.env` as `TUNNEL_TOKEN=...`
4. `docker compose up -d`

Your public URL for the connector will be whatever hostname you chose,
e.g. `https://reddit-mcp.yourdomain.com/mcp`.

## 6. Add it to Claude as a custom connector

In Claude.ai: **Settings → Connectors → Add custom connector**.

- URL: your public HTTPS URL from the tunnel (e.g. `https://reddit-mcp.yourdomain.com/mcp`)
- Add a custom header:
  - Name: `Authorization`
  - Value: `Bearer <your MCP_AUTH_TOKEN>`

Once connected, ask Claude to search Reddit and it'll call
`search_reddit` directly — no more relying on general web search, which
doesn't surface Reddit reliably.

## Security notes

- `MCP_AUTH_TOKEN` gates every tool call. Don't skip setting it — without
  it, anyone with your URL can use your Reddit API quota.
- This is read-only (PRAW `read_only=True`); it can't post, vote, or
  modify anything on Reddit even if someone got past auth.
- Reddit API rate limits apply (roughly 60 requests/min per app) —
  fine for interactive chat use, but don't put this behind something
  that hammers it in a loop.