mcp-reddit 0.1.0__tar.gz

mcp_reddit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+        run: twine upload dist/*

mcp_reddit-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Claude Code
+.claude/settings.local.json
+logs/
+
+# Dependencies
+node_modules/
+vendor/
+.venv/
+venv/
+__pycache__/
+*.pyc
+
+# Build outputs
+dist/
+build/
+.next/
+out/
+*.egg-info/
+
+# Environment
+.env
+.env.local
+.env.*.local
+!.env.example
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Testing
+coverage/
+.nyc_output/
+.pytest_cache/
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+data/
+.claude/
+.mcp.json
+CLAUDE.md

mcp_reddit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_reddit-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: mcp-reddit
+Version: 0.1.0
+Summary: MCP server for scraping Reddit - no API keys required
+Project-URL: Homepage, https://github.com/yourusername/mcp-reddit
+Project-URL: Repository, https://github.com/yourusername/mcp-reddit
+Project-URL: Issues, https://github.com/yourusername/mcp-reddit/issues
+Author: Naman
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anthropic,claude,mcp,reddit,scraper
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: aiofiles>=23.0.0
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pandas>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mcp-reddit
+
+MCP server for scraping Reddit - **no API keys required**.
+
+Scrapes posts, comments, and media from subreddits and user profiles using old.reddit.com and Libreddit mirrors.
+
+## Features
+
+- **No API keys** - Scrapes directly, no Reddit API credentials needed
+- **Media downloads** - Images, videos with audio (requires ffmpeg)
+- **Local persistence** - Query scraped data offline
+- **Rich filtering** - By post type, score, keywords
+- **Comments included** - Full thread scraping
+
+## Installation
+
+```bash
+pip install mcp-reddit
+```
+
+Or with uvx:
+
+```bash
+uvx mcp-reddit
+```
+
+## Configuration
+
+Add to your Claude Desktop or Claude Code settings:
+
+### Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "reddit": {
+      "command": "uvx",
+      "args": ["mcp-reddit"]
+    }
+  }
+}
+```
+
+### Claude Code (`~/.claude/settings.json`)
+
+```json
+{
+  "mcpServers": {
+    "reddit": {
+      "command": "uvx",
+      "args": ["mcp-reddit"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool                   | Description                        |
+| ---------------------- | ---------------------------------- |
+| `scrape_subreddit`     | Scrape posts from a subreddit      |
+| `scrape_user`          | Scrape posts from a user's profile |
+| `get_posts`            | Query stored posts with filters    |
+| `get_comments`         | Query stored comments              |
+| `search_reddit`        | Search across all scraped data     |
+| `get_top_posts`        | Get highest scoring posts          |
+| `list_scraped_sources` | List all scraped subreddits/users  |
+
+## Example Usage
+
+```
+"Scrape the top 50 posts from r/LocalLLaMA"
+
+"Search my scraped data for posts about 'fine-tuning'"
+
+"Get the top 10 posts from r/ClaudeAI by score"
+```
+
+## Data Storage
+
+Data is stored in `~/.mcp-reddit/data/` by default.
+
+Set `MCP_REDDIT_DATA_DIR` environment variable to customize:
+
+```json
+{
+  "mcpServers": {
+    "reddit": {
+      "command": "uvx",
+      "args": ["mcp-reddit"],
+      "env": {
+        "MCP_REDDIT_DATA_DIR": "/path/to/your/data"
+      }
+    }
+  }
+}
+```
+
+## Optional: Video with Audio
+
+To download Reddit videos with audio, install ffmpeg:
+
+```bash
+# macOS
+brew install ffmpeg
+
+# Ubuntu/Debian
+sudo apt install ffmpeg
+
+# Windows
+choco install ffmpeg
+```
+
+## Credits
+
+Built on top of [reddit-universal-scraper](https://github.com/ksanjeev284/reddit-universal-scraper)
+by [@ksanjeev284](https://github.com/ksanjeev284) - a full-featured Reddit scraper with
+analytics dashboard, REST API, and plugin system.
+
+## License
+
+MIT

mcp_reddit-0.1.0/README.md

@@ -0,0 +1,122 @@
+# mcp-reddit
+
+MCP server for scraping Reddit - **no API keys required**.
+
+Scrapes posts, comments, and media from subreddits and user profiles using old.reddit.com and Libreddit mirrors.
+
+## Features
+
+- **No API keys** - Scrapes directly, no Reddit API credentials needed
+- **Media downloads** - Images, videos with audio (requires ffmpeg)
+- **Local persistence** - Query scraped data offline
+- **Rich filtering** - By post type, score, keywords
+- **Comments included** - Full thread scraping
+
+## Installation
+
+```bash
+pip install mcp-reddit
+```
+
+Or with uvx:
+
+```bash
+uvx mcp-reddit
+```
+
+## Configuration
+
+Add to your Claude Desktop or Claude Code settings:
+
+### Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "reddit": {
+      "command": "uvx",
+      "args": ["mcp-reddit"]
+    }
+  }
+}
+```
+
+### Claude Code (`~/.claude/settings.json`)
+
+```json
+{
+  "mcpServers": {
+    "reddit": {
+      "command": "uvx",
+      "args": ["mcp-reddit"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool                   | Description                        |
+| ---------------------- | ---------------------------------- |
+| `scrape_subreddit`     | Scrape posts from a subreddit      |
+| `scrape_user`          | Scrape posts from a user's profile |
+| `get_posts`            | Query stored posts with filters    |
+| `get_comments`         | Query stored comments              |
+| `search_reddit`        | Search across all scraped data     |
+| `get_top_posts`        | Get highest scoring posts          |
+| `list_scraped_sources` | List all scraped subreddits/users  |
+
+## Example Usage
+
+```
+"Scrape the top 50 posts from r/LocalLLaMA"
+
+"Search my scraped data for posts about 'fine-tuning'"
+
+"Get the top 10 posts from r/ClaudeAI by score"
+```
+
+## Data Storage
+
+Data is stored in `~/.mcp-reddit/data/` by default.
+
+Set `MCP_REDDIT_DATA_DIR` environment variable to customize:
+
+```json
+{
+  "mcpServers": {
+    "reddit": {
+      "command": "uvx",
+      "args": ["mcp-reddit"],
+      "env": {
+        "MCP_REDDIT_DATA_DIR": "/path/to/your/data"
+      }
+    }
+  }
+}
+```
+
+## Optional: Video with Audio
+
+To download Reddit videos with audio, install ffmpeg:
+
+```bash
+# macOS
+brew install ffmpeg
+
+# Ubuntu/Debian
+sudo apt install ffmpeg
+
+# Windows
+choco install ffmpeg
+```
+
+## Credits
+
+Built on top of [reddit-universal-scraper](https://github.com/ksanjeev284/reddit-universal-scraper)
+by [@ksanjeev284](https://github.com/ksanjeev284) - a full-featured Reddit scraper with
+analytics dashboard, REST API, and plugin system.
+
+## License
+
+MIT

mcp_reddit-0.1.0/docs/worklog.md

@@ -0,0 +1,30 @@
+# mcp-reddit Development Worklog
+
+**RULES:**
+- **ONLY append new entries to the TOP** - never edit or delete older entries
+- **Run `date -u +"%Y-%m-%d %H:%M:%S UTC"` to get the timestamp** - do NOT guess
+
+## 2025-12-28 07:40:07 UTC
+
+**Activity**: Created open-source MCP Reddit package
+**What**: Built standalone MCP server for Reddit scraping, ready for PyPI
+**Details**:
+- Researched existing Reddit MCPs (Hawstein, Arindam) - ours has unique features (media download, local persistence, no API keys)
+- Followed Anthropic's 3-tier distribution model (PyPI → MCP Registry → Anthropic Directory)
+- Created src/mcp_reddit/ with server.py (7 tools with annotations) and scraper.py (async)
+- Added pyproject.toml, server.json, README with credits to @ksanjeev284
+- Installed Python 3.12 via Homebrew, tested package installation
+- Verified all MCP tools work (list_scraped_sources, get_top_posts, search_reddit, etc.)
+- Initialized git repo, committed initial package
+**Next**: Push to GitHub, add PYPI_TOKEN secret, create release to publish
+
+---
+
+## 2025-12-28 06:56:59 UTC
+
+**Activity**: Project setup
+**What**: Initialized Claude Code configuration
+**Details**: Added CLAUDE.md, hooks, skills, output styles, worklog
+**Next**: Start development
+
+---

mcp_reddit-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "mcp-reddit"
+version = "0.1.0"
+description = "MCP server for scraping Reddit - no API keys required"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Naman" }
+]
+keywords = ["mcp", "reddit", "scraper", "claude", "anthropic"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "pandas>=2.0.0",
+    "aiohttp>=3.9.0",
+    "aiofiles>=23.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+]
+
+[project.scripts]
+mcp-reddit = "mcp_reddit.server:main"
+
+[project.urls]
+Homepage = "https://github.com/yourusername/mcp-reddit"
+Repository = "https://github.com/yourusername/mcp-reddit"
+Issues = "https://github.com/yourusername/mcp-reddit/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_reddit"]

mcp_reddit-0.1.0/server.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
+  "name": "io.github.yourusername/mcp-reddit",
+  "description": "Scrape Reddit without API keys - posts, comments, media from subreddits and users",
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registry_type": "pypi",
+      "identifier": "mcp-reddit"
+    }
+  ],
+  "tools": [
+    {
+      "name": "scrape_subreddit",
+      "description": "Scrape posts from a subreddit"
+    },
+    {
+      "name": "scrape_user",
+      "description": "Scrape posts from a user's profile"
+    },
+    {
+      "name": "get_posts",
+      "description": "Query stored posts with filters"
+    },
+    {
+      "name": "get_comments",
+      "description": "Query stored comments"
+    },
+    {
+      "name": "search_reddit",
+      "description": "Search across all scraped data"
+    },
+    {
+      "name": "get_top_posts",
+      "description": "Get highest scoring posts"
+    },
+    {
+      "name": "list_scraped_sources",
+      "description": "List all scraped subreddits/users"
+    }
+  ]
+}

mcp_reddit-0.1.0/src/mcp_reddit/__init__.py

@@ -0,0 +1,10 @@
+"""
+MCP Reddit - Scrape Reddit without API keys
+Based on reddit-universal-scraper by @ksanjeev284
+https://github.com/ksanjeev284/reddit-universal-scraper
+"""
+from .server import main
+from .scraper import run_scraper, scrape_async
+
+__version__ = "0.1.0"
+__all__ = ["main", "run_scraper", "scrape_async"]