reddit-mcp

Conector MCP de solo lectura para la API de datos de Reddit, orientado al OAuth de tarjeta de conexión de Cursor / Grok Bot. Se ejecuta como un Cloudflare Worker que utiliza MCP Streamable HTTP y pasa a través el token Authorization: Bearer del llamante a https://oauth.reddit.com.

Repositorio: https://github.com/pmsorhaindo/reddit-mcp

Arquitectura

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)

¿Por qué JSON-RPC mínimo (no el SDK completo de MCP)?

@modelcontextprotocol/sdk históricamente apuntada a transportes de Node. Este Worker implementa una superficie JSON-RPC Streamable HTTP nativa para Workers y con pocas dependencias (initialize / tools/list / tools/call) que coincide con lo que Cursor/Grok necesitan para la llamada a herramientas, sin Durable Objects ni almacenes de sesión. Eso encaja con la transmisión de bearer: el Worker nunca guarda los tokens de refresco de Reddit.

Herramientas

Todas las herramientas devuelven JSON compacto (campos de texto truncados). limit predetermina a 25, con máximo de 100.

Límite de tasa

• Las llamadas salientes a Reddit se serializan por isolate de Worker (cadena de promesas).

• Se respetan X-Ratelimit-Remaining / X-Ratelimit-Reset antes de la siguiente llamada.

• Los HTTP 429 / 503 provocan reintentos limitados con Retry-After o retroceso exponencial.

Higiene de secretos

Nunca subas secretos reales.

• El .gitignore robusto cubre .env, .dev.vars, .wrangler/, node_modules/, dist/, credentials*.json, .mcp-auth/.

• Solo se suben los archivos de entorno de ejemplo: .dev.vars.example, .env.example.

• wrangler.toml no incluye secretos en línea.

• Los errores y los registros de console nunca incluyen cabeceras Authorization, tokens ni valores de variables de entorno secretos.

• Los payloads de error de las tools son solo estado/mensaje — sin cuerpos de respuesta de aguas arriba que puedan reflejar credenciales.

Related MCP server: reddit-mcp

Configuración de la app de Reddit

1. Crea una app de Reddit en https://www.reddit.com/prefs/apps (tipo web app o installed app según lo que corresponda a tu cliente).

2. Añade las URIs de redirección:

   • http://localhost:8787/callback — wrangler local / pruebas manuales

   • https://www.cursor.com/agents/mcp/oauth/callback — tarjeta de conexión de Cursor

3. Solicita los alcances (separados por comas en las URLs de autorización de Reddit):

   • identity,read,mysubreddits,history

4. Anota client_id / client_secret para el cliente OAuth (Cursor / tu gestor de secretos). No los pongas en este repositorio ni en wrangler.toml.

Supuestos de descubrimiento OAuth

• /.well-known/oauth-authorization-server publica:

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

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

• Este Worker no realiza el intercambio del código de autorización y no almacena tokens de refresco.

• Cursor/Grok completan el OAuth con Reddit (usando las credenciales de la app de Reddit que configures en el cliente) y luego envían Authorization: Bearer <access_token> en las solicitudes MCP.

• issuer en los metadatos es el origen de este Worker para que los clientes MCP puedan descubrir la documentación desde la URL base del MCP; la autorización y el token siguen sucediendo en Reddit.

• Los alcances de Reddit se suelen separar con comas en la URL de autorización; the clientes deben unir los alcances en consecuencia.

Despliegue en Cloudflare

Requisitos previos: Node 22+, cuenta de Cloudflare y Wrangler con sesión iniciada (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

Ejemplo de forma de USER_AGENT (solo marcador de posición):

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

Después del despliegue, registra la URL de workers.dev o del dominio personalizado, p. ej. https://reddit-mcp.<account>.workers.dev.

Añadir servidor MCP (Cursor / Grok)

Configura AddMcpServer (o la tarjeta de conexión equivalente) con:

Tu cliente debe usar el client id y el client secret de tu app de Reddit y la URI de redirección de Cursor mencionada arriba. Tras la autenticación, las llamadas a las herramientas de MCP deben incluir el token de acceso de Reddit como cabecera Bearer; este Worker lo reenvía al servicio aguas arriba.

Pruebas de humo

Reemplaza $BASE y $TOKEN localmente — no subas tokens.

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":{}}}'

Resultado esperado: respuestas JSON-RPC; get_me devuelve campos de perfil compactos. Si falta el Bearer, error JSON-RPC Unauthorized sin filtrar cabeceras.

Scripts

Fuera de alcance

• Escribir, votar, enviar mensajes, moderar o la API de Ads

• Almacenar tokens de refresco de Reddit o secretos de cliente en el Worker

• Realizar el intercambio del código OAuth en /callback

• Sesiones completas de MCP resources/prompts/sampling/elicitation

• Bóvedas de tokens multiusuario / almacenes de sesión de Durable Objects Storage

• Garantizar una coordinación global del límite de tasa entre isolates (los límites son por isolate y dependen de las cabeceras de Reddit)

Licencia

Privada / sin publicar a menos que añadas un archivo de licencia.