reddit-mcp

Un servidor de Protocolo de Contexto de Modelo (MCP) de solo lectura que envuelve la API de Reddit para la navegación por subreddits, búsqueda dentro de subreddits, recuperación de árboles de comentarios y búsqueda de actividad de usuarios. Diseñado para el seguimiento personal de r/homelabsales, r/hardwareswap y subreddits similares a través de Claude Code y Claude Desktop. Escrito en Python, se ejecuta localmente sobre stdio.

Niveles de autenticación (todos opcionales)

El servidor detecta automáticamente qué nivel utilizar según las variables de entorno que establezcas:

Nuevos usuarios: comiencen con el nivel anónimo. Reddit finalizó la creación de claves API de autoservicio en noviembre de 2025 (Política de Constructor Responsable), por lo que obtener credenciales OAuth ahora requiere un proceso de aprobación que generalmente rechaza los scripts personales. El nivel anónimo cubre todas las rutas de lectura que implementa este servidor. Consulta la sección 3.2 de docs/design.md para conocer la historia completa.

Related MCP server: Reddit MCP Server

Instalación del plugin (desarrollo local)

Todo el repositorio es un plugin de Claude Code (habilidad + comandos de barra + servidor MCP empaquetado). Para probarlo localmente:

cd /Users/conrad/Ai/reddit_mcp
uv pip install -e .                                          # one-time, sets up the MCP server in a venv
claude plugin marketplace add /Users/conrad/Ai/reddit_mcp    # register this repo as a local marketplace
claude plugin install reddit-deal-hunter@reddit-mcp-local    # install + enable the plugin

Reinicia Claude Code. En la primera activación de MCP, se te solicitarán cinco campos (reddit_user_agent, reddit_client_id, reddit_client_secret, reddit_username, reddit_password), todos opcionales. Deja cualquiera o todos en blanco para permanecer en un nivel inferior. Se recomienda establecer reddit_user_agent independientemente del nivel; utiliza el formato macos:reddit-mcp:0.2 (by /u/tu_nombre_de_usuario).

Una vez activado, la habilidad, los comandos /reddit-deal-hunter:scan y /reddit-deal-hunter:thread-check, y las cuatro herramientas MCP (get_subreddit_posts, search_subreddit, get_post_details, user_analysis) estarán disponibles.

Aviso: a partir de abril de 2026, es posible que la capa MCP del paquete de plugins no adjunte herramientas a las sesiones de Claude Code en cada instalación (el mcpServers en línea en plugin.json está documentado como compatible, pero el comportamiento del tiempo de ejecución de la GUI varía). Si la habilidad y los comandos de barra aparecen pero las herramientas mcp__reddit_mcp__* no, vuelve a la ruta de instalación solo para MCP a continuación. Consulta docs/tool-ux-findings.md y HANDOFF.md (anexo de la sesión 5) para más detalles.

Instalación manual (solo MCP, sin plugin) — actualmente la ruta más fiable

Si solo deseas el servidor MCP (sin habilidad, sin comandos de barra), o si la instalación de la capa de plugin anterior no adjunta las herramientas MCP a tu sesión, regístralo directamente con Claude Code en el ámbito de usuario:

cd /Users/conrad/Ai/reddit_mcp
uv venv --python 3.12
uv pip install -e .

# Anonymous (zero credentials):
claude mcp add reddit_mcp \
  --scope user \
  --env REDDIT_USER_AGENT="macos:reddit-mcp:0.2 (by /u/yourusername)" \
  -- uv run --directory /Users/conrad/Ai/reddit_mcp reddit-mcp

# OAuth app-only (add client creds):
claude mcp add reddit_mcp \
  --scope user \
  --env REDDIT_USER_AGENT="macos:reddit-mcp:0.2 (by /u/yourusername)" \
  --env REDDIT_CLIENT_ID=YOUR_REDDIT_CLIENT_ID \
  --env REDDIT_CLIENT_SECRET=YOUR_REDDIT_CLIENT_SECRET \
  -- uv run --directory /Users/conrad/Ai/reddit_mcp reddit-mcp

Verifica con claude mcp list (espera reddit_mcp ✓ Connected) y reinicia Claude Code para que las herramientas se adjunten a las nuevas sesiones.

Consulta la sección 7 de docs/design.md para el registro en Claude Desktop y otras conexiones de cliente.

Diseño del repositorio

reddit-mcp/
├── .claude-plugin/
│   ├── plugin.json                 # plugin manifest + inline mcpServers block
│   └── marketplace.json            # single-plugin local-marketplace descriptor
├── CLAUDE.md                       # repo-specific working notes for Claude Code
├── commands/                       # user-invoked slash commands
│   ├── scan.md                     # /reddit-deal-hunter:scan <query>
│   └── thread-check.md             # /reddit-deal-hunter:thread-check <permalink-or-id>
├── docs/
│   ├── design.md                   # full design, the authoritative read
│   ├── supply-chain-baseline.md    # pinned-deps audit baseline
│   └── tool-ux-findings.md         # known issues surfaced by the live eval run
├── evals/
│   └── reddit_eval.xml             # 10 qa_pairs for mcp-builder evaluation
├── pyproject.toml                  # mcp, httpx (pinned)
├── reddit_mcp.py                   # the MCP server (uses mcp SDK FastMCP)
├── skills/
│   └── deal-hunter/SKILL.md        # model-invoked deal-watching heuristics
└── tests/test_smoke.py             # module import + tool registration

Estado

Pre-v1. El nivel anónimo funciona de principio a fin sin credenciales (validado en vivo contra Reddit; pasa el 10/10 de la suite de evaluación). Las rutas de actualización a OAuth funcionan si tienes credenciales. Trabajo restante para la v1: una refactorización de la proyección de respuesta de herramientas rastreada en docs/tool-ux-findings.md. Lanzamiento público después de que la v1 sea validada.

Consulta docs/design.md para el diseño completo y la justificación, CLAUDE.md para la versión de notas de trabajo, y HANDOFF.md para el traspaso entre sesiones.

Licencia

MIT.