reddit-mcp

Cursor / Grok Bot connect-card OAuth 연동용 읽기 전용 Reddit Data API MCP 커넥터입니다. Cloudflare Worker로 실행되며 MCP Streamable HTTP를 따라 호출자의 Authorization: Bearer 토큰을 https://oauth.reddit.com으로 그대로 전달합니다.

리포지토리: https://github.com/pmsorhaindo/reddit-mcp

아키텍처

Cursor / Grok Bot
   │  OAuth (connect-card) against Reddit authorize/token
   │  then MCP JSON-RPC with Bearer access token
   ▼
Cloudflare Worker (this repo)
   │  POST /mcp  → tools/list, tools/call
   │  GET  /.well-known/oauth-*  → discovery pointing at Reddit
   ▼
https://oauth.reddit.com  (User-Agent from env, Bearer passthrough)

왜 최소한의 JSON-RPC인가 (전체 MCP SDK를 쓰지 않는 이유)?

@modelcontextprotocol/sdk는 원래 Node 전송 계층을 대상으로 했습니다. 이 Worker는 Durable Objects나 세션 저장소 없이 Cursor/Grok이 도구 호출에 필요로 하는 기능을 충족하는 Workers 네이티브 방식의, 의존성이 낮은 Streamable HTTP JSON-RPC 인터페이스(initialize / tools/list / tools/call)를 구현합니다. 이는 Bearer 패스스루 방식에 잘 맞습니다. Worker는 Reddit 리프레시 토큰을 절대 보관하지 않습니다.

도구

모든 도구는 간결한 JSON(텍스트 필드는 잘림)을 반환합니다. limit의 기본값은 25이며, 최대 100까지 허용됩니다.

비율 제한

• Reddit으로 나가는 호출은 Worker isolate 단위로 직렬화됩니다(프록시 체인).

• 응답의 X-Ratelimit-Remaining / X-Ratelimit-Reset 값을 다음 호출 전에 존중합니다.

• HTTP 429 / 503 응답 시 Retry-After 또는 지수 백오프 방식으로 제한된 재시도를 수행합니다.

시크릿 관리

실제 시크릿은 절대 커밋하지 마세요.

• 강력한 .gitignore로 .env, .dev.vars, .wrangler/, node_modules/, dist/, credentials*.json, .mcp-auth/를 제외합니다.

• 커밋되는 것은 예시용 환경 파일뿐입니다: .dev.vars.example, .env.example.

• wrangler.toml에는 인라인 시크릿이 없습니다.

• 오류 및 console 로그에는 Authorization 헤더, 토큰, 비밀 환경 변수 값이 절대 포함되지 않습니다.

• 도구 오류 응답은 상태 코드/메시지만 포함하며, 자격 증명이 반사될 수 있는 업스트림 응답 본문은 포함하지 않습니다.

Related MCP server: reddit-mcp

Reddit 앱 설정

1. https://www.reddit.com/prefs/apps에서 Reddit 앱을 생성합니다(클라이언트에 따라 web app 또는 installed app 선택).

2. 리다이렉트 URI를 추가하세요:

   • http://localhost:8787/callback — 로컬 wrangler / 수동 테스트

   • https://www.cursor.com/agents/mcp/oauth/callback — Cursor connect-card

3. 범위(scopes) 요청(Reddit 인가 URL에서 쉼표로 구분):

   • identity,read,mysubreddits,history

4. OAuth 클라이언트(Cursor / 시크릿 관리자)의 client_id / client_secret을 기록해 두세요. **이 저장소나 wrangler.toml에 넣지 마세요.

OAuth 디스커버리 가정

• /.well-known/oauth-authorization-server는 다음을 공지합니다:

  • authorization_endpoint: https://www.reddit.com/api/v1/authorize

  • token_endpoint: https://www.reddit.com/api/v1/access_token

• 이 Worker는 인가 코드 교환을 수행하지 않으며 리프레시 토큰을 저장하지 않습니다.

• Cursor/Grok은 (여러분이 클라이언트에 구성하는 Reddit 앱 자격 증명을 사용해) Reddit과의 OAuth를 완료한 다음, MCP 요청에 Authorization: Bearer <access_token> 헤더를 보냅니다.

• 메타데이터의 issuer는 이 Worker의 오리진으로 설정되어, MCP 클라이언트가 MCP 기본 URL에서 문서를 발견할 수 있게 합니다. authorize/token은 여전히 Reddit에서 이루어집니다.

• Reddit 범위는 전통적으로 인가 URL에서 쉼표로 구분됩니다 — 클라이언트는 그에 맞게 범위를 결합해야 합니다.

Cloudflare 배포

전제 조건: Node 22+, Cloudflare 계정, Wrangler 로그인(npx wrangler login).

git clone https://github.com/pmsorhaindo/reddit-mcp.git
cd reddit-mcp
npm install

# Local secrets (gitignored)
cp .dev.vars.example .dev.vars
# edit USER_AGENT — must identify you per Reddit API rules

npm run typecheck
npm run dev          # http://127.0.0.1:8787

# Production secret (not committed)
npx wrangler secret put USER_AGENT
npm run deploy

USER_AGENT 예시 형태(자리표시자일 뿐):

cloudflare-worker:reddit-mcp:0.1.0 (by /u/YOUR_REDDIT_USERNAME)

배포 후에는 workers.dev 또는 사용자 지정 도메인 URL을 기록해 두세요(예: https://reddit-mcp.<account>.workers.dev).

MCP 서버 추가 (Cursor / Grok)

다음을 사용해 AddMcpServer(또는 그에 상당하는 connect-card)를 구성하세요:

클라이언트는 여러분의 Reddit 앱 client id/secret과 위의 Cursor 리다이렉션 URI를 사용해야 합니다. 인증 후 MCP 요청에는 Reddit 액세스 토큰이 Bearer 헤더로 포함되어야 하며, 이 Worker는 그대로 업스트림으로 전달합니다.

스모크 테스트

로컬 환경에서 $BASE와 $TOKEN을 교체하세요 — 토큰을 커밋하지 마세요.

BASE=http://127.0.0.1:8787
TOKEN=reddit_access_token_here

# Health
curl -sS "$BASE/health"

# OAuth metadata
curl -sS "$BASE/.well-known/oauth-authorization-server"
curl -sS "$BASE/.well-known/oauth-protected-resource"

# MCP initialize
curl -sS -X POST "$BASE/mcp" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}'

# tools/list
curl -sS -X POST "$BASE/mcp" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# tools/call get_me (requires valid Bearer)
curl -sS -X POST "$BASE/mcp" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_me","arguments":{}}}'

예상 결과: JSON-RPC 결과, get_me는 간결한 프로필 필드를 반환합니다. Bearer가 없으면 클라이언트의 헤더를 유출하지 않고 JSON-RPC 오류 Unauthorized를 반환합니다.

스크립트

범위 외

• 글쓰기, 투표, 메시지 보내기, 모려 활동, Ads API

• Worker에 Reddit 리프레시 토큰 또는 클라이언트 시크릿 저장

• /callback에서 OAuth 코드 교환 수행

• 전체 MCP 리소스/프롬프트/샘플링/elicitation 세션

• 다중 테넌시 토큰 저장소 / Durable Object 세션 저장소

• 격리 간 전역 비율 제한 보장(한도는 격리 단위당 + Reddit 헤더 기준)

라이선스

라이선스 파일을 추가하지 않는 한 비공개/미배포 상태입니다.