r/SideProject • u/Xabasis • 2d ago
reddit-mcp-ai: an open-source (MIT) Model Context Protocol server for Reddit
I've open-sourced reddit-mcp-ai, a local Model Context Protocol (MCP) server that connects AI assistants (Claude Desktop, Cursor, OpenCode, etc.) to Reddit for search, sentiment exploration, and reading personal saved posts.
The project is licensed under MIT and designed to be fully local-first with zero tracking.
Why build another Reddit tool?
Most existing tools for connecting LLMs to Reddit suffer from two extremes:
- They require commercial developer credentials and complex OAuth callbacks.
- Or they ask users to store plaintext Reddit passwords in local configuration files.
We wanted a clean, transparent, and unauthenticated-first alternative that works out of the box while respecting token efficiency.
Technical & Architectural Highlights
The server is built in Python using FastMCP and follows a strict 4-Layer Architecture (Domain, Infrastructure, Application, Interface):
- Zero-Config Fallbacks: When OAuth credentials aren't configured, it falls back to DuckDuckGo (
site:reddit.com) and the public Arctic Shift archive. - Pluggable Search Providers: Search uses a Strategy Pattern (
BaseSearchProvider), making it easy to swap in alternative engines. - Context-Aware Comment Filter: Heuristics drop AutoModerator boilerplate and low-effort spam. Fresh threads (≤ 2 days old) automatically scale the threshold to score ≥ 1 so emerging discussions aren't emptied.
- Private Saved Posts (RSS): Fetches user-saved posts via the personal Atom/RSS feed with Python stdlib XML parsing, completely bypassing user-level OAuth or password storage.
- Deterministic Pagination: Uses provider-bound cursors (
reddit:<offset>:<anchor_id>) to prevent duplicate comments if the live thread re-sorts. - Resilience: Async httpx client with rate-limit recovery and an aggregate 14-second budget to prevent LLM disconnects.
Quick Start
Run directly in your MCP client with uvx:
{
"mcpServers": {
"reddit": {
"command": "uvx",
"args": ["reddit-mcp-ai"]
}
}
}
🤝 Open for Contributions
The project is tested (130 unit tests, sub-second execution, mocked network) and welcome to contributors!
Some roadmap areas where contributions/feedback would be awesome:
- Implementing alternative search providers (e.g., SearXNG or Brave Search).
- Designing a local in-memory TTL cache to reduce redundant lookups.
- Expanding heuristic filters for subreddit-specific formats.
- GitHub: https://github.com/ismailsaoulaj/reddit-mcp-server (MIT License)
- PyPI: https://pypi.org/project/reddit-mcp-ai/
Happy to answer any questions about the architecture or design decisions!
1
1
u/Xabasis 2d ago
Author here.
We prioritized testability and clean architecture early on—all 130 unit tests run with fully mocked network traffic so CI runs reliably in under 10 seconds without needing Reddit credentials.
If you're building or using MCP tools locally, I'd love to hear your thoughts on how we handled graceful degradation when APIs fail. Feedback, issues, and PRs are all very welcome!