Reddit MCP Server

Дайте вашему ИИ-ассистенту живое структурированное окно в Reddit — без каких-либо API-ключей.

Reddit MCP Server — это сервер с открытым исходным кодом по протоколу Model Context Protocol (MCP), который подключает ИИ-ассистентов (Claude, Cursor, Open WebUI и другие) к контенту Reddit в реальном времени. Он предоставляет структурированные инструменты для поиска обсуждений, извлечения мнений сообщества и отслеживания нишевых трендов — с отказоустойчивым многоуровневым резервным движком, работающим даже без каких-либо учётных данных.

# Get started in one command — no sign-up, no API keys
uvx reddit-mcp-ai

🗺️ Как это работает (последовательность потока данных)

Ниже представлена визуальная диаграмма последовательности, показывающая, как ИИ-модель взаимодействует с этим сервером, включая нашу систему резервирования без конфигурации (Zero-Config Fallback):

sequenceDiagram
    autonumber
    actor AI as AI Assistant (Claude/Cursor)
    participant MCP as FastMCP Server (STDIO)
    participant Tools as Application Tools
    participant Reddit as Reddit API (OAuth)
    participant Fallback as DDG & Arctic Shift

    AI->>MCP: Request (e.g., search_knowledge)
    MCP->>Tools: Route request
    Tools->>Reddit: Attempt Fetch (Resilient HTTP)
    alt Has OAuth Credentials & API Healthy
        Note over Reddit,Tools: Handles 429 (Rate Limits) with Retry-After backoff!
        Reddit-->>Tools: Return Official JSON payload
    else Zero-Config OR Reddit API Fails
        Note over Tools,Fallback: Graceful Degradation Active
        Tools->>Fallback: Execute Search / Fetch Archive
        Fallback-->>Tools: Return Alternative JSON payload
    end
    Tools->>Tools: Refine comments (filter bots & short noise)
    Tools-->>MCP: Map to Domain Models (Pydantic)
    MCP-->>AI: Return clean JSON-RPC Response (stdout-safe)

✨ Возможности

• 🚀 Готовность к работе без конфигурации: Полностью работает «из коробки». API-ключи Reddit не требуются — автоматически переключается на DuckDuckGo и архив Arctic Shift.
• 🛡️ Каскадный многоуровневый движок: Official OAuth → Session Cookie → Browser-Impersonated JSON → Arctic Shift RSS → DDG. ИИ всегда получает данные, даже когда Reddit ограничивает частоту запросов или учётные данные отсутствуют.
• 🚦 Встроенная защита от блокировок: Ограничитель частоты запросов на основе token bucket, глобальный семафор конкурентности и объединение запросов singleflight предотвращают блокировки WAF 403 и баны IP при интенсивном трафике от ИИ.
• � Отказоустойчивый HTTP-клиент: Экспоненциальная задержка повторов с учётом заголовка Retry-After, ограниченный совокупный дедлайн в 14 секунд и автоматическое самовосстановление OAuth-токена при ошибках 401 во время выполнения запроса.
• 🤖 Фильтрация, безопасная для LLM: Отбрасывает AutoModerator, ботов и малозначимые комментарии до того, как они попадут в модель — экономя токены и снижая шум.
• ⏱️ Строгая защита от таймаутов: Таймауты, принудительно заданные декораторами, возвращают чистые JSON-RPC-ответы вместо зависания ИИ-клиента.
• 🌐 Транспорт STDIO и SSE: Работает как локальный CLI-инструмент для Claude/Cursor или как Docker-микросервис на порту 8000 для Open WebUI, LibreChat и n8n.

🧰 Доступные инструменты

⚙️ Предварительные требования и настройка

Требования

• Python 3.11 или выше
• Учётные данные приложения Reddit API (необязательно, но рекомендуется для данных о трендах в реальном времени и более высоких лимитов запросов)

Быстрый старт

Вы можете запустить этот сервер напрямую без установки с помощью uvx (рекомендуется) или pipx:

# Run locally (STDIO mode) for Cursor/Claude
uvx reddit-mcp-ai

# OR run as a background service (Streamable HTTP mode) for Open WebUI / Web clients
uvx reddit-mcp-ai --transport http --host 0.0.0.0 --port 8000

Настройте окружение (необязательно):

Чтобы разблокировать официальный Reddit API, аутентификацию через cookie или сохранённые посты, вы можете либо передать переменные окружения через конфигурацию вашего MCP-клиента, либо создать глобальный файл конфигурации по пути ~/.config/reddit-mcp-server/.env (Mac/Linux) или %APPDATA%\reddit-mcp-server\.env (Windows):

# Optional: Official Reddit App Credentials
REDDIT_CLIENT_ID="your_client_id_here"
REDDIT_CLIENT_SECRET="your_client_secret_here"

# Optional: Direct Cookie Auth (Instant sub-second access & pagination)
# Extract from DevTools -> Application -> Cookies -> reddit_session (Use an alt account)
REDDIT_SESSION_COOKIE="your_reddit_session_cookie_here"

# Optional: Concurrency & Rate Limiting Shields
REDDIT_MAX_CONCURRENCY=4
REDDIT_RATE_LIMIT_PER_MINUTE=40

Также рассмотрите возможность установить REDDIT_USER_AGENT в описательное уникальное значение — руководства по API Reddit требуют этого даже в режиме без конфигурации. Если значение не задано, сервер генерирует значение по умолчанию со случайным суффиксом для каждой установки (сохраняемым в вашем каталоге состояния XDG, чтобы оно оставалось стабильным между перезапусками).

Чтобы включить инструмент get_saved_posts, добавьте URL вашей приватной ленты сохранённых элементов:

REDDIT_SAVED_RSS_URL="https://www.reddit.com/user/YOUR_USERNAME/saved.rss?feed=YOUR_FEED_TOKEN&user=YOUR_USERNAME"

Выполнив вход в аккаунт, откройте reddit.com/prefs/feeds/ и скопируйте точную ссылку для «ваших сохранённых ссылок». Токен feed — это учётные данные вашего аккаунта — обращайтесь с ним как с паролем (сервер никогда не записывает его в логи и отклоняет запросы к хостам, отличным от Reddit). Лента содержит последние ~100 сохранённых элементов; баллы и количество комментариев через неё недоступны.

🐳 Установка через Docker

Предоставлен многоэтапный (multi-stage) Dockerfile. Контейнер настроен на запуск в режиме SSE (HTTP) по умолчанию на порту 8000, что делает его идеальным микросервисом.

# Build the image
docker build -t reddit-mcp-server .

# Run it in the background
docker run -d -p 8000:8000 --name reddit-mcp reddit-mcp-server

Пример Docker Compose

services:
  reddit-mcp:
    build: .
    container_name: reddit-mcp
    ports:
      - "8000:8000"
    restart: unless-stopped
    environment:
      # Optional Configuration
      - REDDIT_CLIENT_ID=your_id_optional
      - REDDIT_CLIENT_SECRET=your_secret_optional

Примечание: При использовании Docker в режиме STDIO замените команду в конфигурациях клиентов на docker, а аргументы — на run -i --rm reddit-mcp-server.

🛠️ Конфигурация для AI-клиентов

1. Claude Desktop

Отредактируйте ваш файл конфигурации: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json

Простая настройка без конфигурации (рекомендуется):

{
  "mcpServers": {
    "reddit": {
      "command": "uvx",
      "args": [
        "reddit-mcp-ai"
      ]
    }
  }
}

Полная настройка с дополнительными функциями (OAuth и сохранённые посты):

{
  "mcpServers": {
    "reddit": {
      "command": "uvx",
      "args": [
        "reddit-mcp-ai"
      ],
      "env": {
        "REDDIT_CLIENT_ID": "your_client_id_here",
        "REDDIT_CLIENT_SECRET": "your_client_secret_here",
        "REDDIT_SAVED_RSS_URL": "your_feed_url_here"
      }
    }
  }
}

2. Cursor / OpenCode

Перейдите в Настройки > Функции > MCP и добавьте новый сервер на основе команды: - Тип: команда - Имя: Reddit - Команда: uvx reddit-mcp-ai - Переменные окружения: (необязательно) добавьте сюда REDDIT_SAVED_RSS_URL и ссылку на вашу ленту, если хотите использовать функцию сохранённых постов.

3. Open WebUI (и другие веб-клиенты)

При запуске сервера через Docker или в режиме Streamable HTTP: 1. Перейдите в Панель администратора > Настройки > Внешние подключения / Инструменты. 2. Добавьте новый MCP-сервер. 3. Тип: MCP (Streamable HTTP) 4. URL: http://localhost:8000/mcp (используйте http://host.docker.internal:8000/mcp, если Open WebUI также запущен в Docker).

🧪 Опыт разработчика (DX) и тестирование

Мы уделяем первостепенное внимание высокому покрытию тестами. Мы мокируем весь сетевой трафик, обеспечивая мгновенное и надёжное выполнение тестов.

Запуск тестов

# Install development dependencies (using uv — recommended)
uv sync --locked --extra dev

# Or with pip
pip install -e ".[dev]"

# Execute pytest
uv run pytest tests/

Ручное тестирование с помощью MCP Inspector

npx @modelcontextprotocol/inspector uvx reddit-mcp-ai

Эта команда запустит веб-интерфейс в браузере, где вы сможете напрямую вызывать инструменты search_knowledge, explore_reddit_discussions, extract_public_opinion и analyze_niche_trends и изучать JSON-ответы.

🤝 Участие в разработке

Любой вклад приветствуется! Вот как начать:

1. Сделайте форк репозитория и клонируйте его.
2. Установите зависимости: uv sync --locked --extra dev
3. Создайте ветку: git checkout -b feature/your-feature-name
4. Внесите изменения, затем запустите линтер и тесты:

   uv run ruff check .
   uv run ruff format .
   uv run pytest tests/

1. Откройте pull request — CI выполнится автоматически.

Сведения об архитектуре см. в docs/architecture.md. Чтобы добавить собственный поисковый провайдер, см. src/reddit_mcp/infrastructure/search/providers/README.md.

Перед отправкой, пожалуйста, ознакомьтесь с CONTRIBUTING.md и CODE_OF_CONDUCT.md.

👥 Участники и особая благодарность

Огромная благодарность каждому, кто помогает сделать Reddit MCP Server ещё лучше!

• @brianluby — Значительный вклад в основную архитектуру, укрепление безопасности и проектирование отказоустойчивости.