# SubScraper Reddit MCP Server

[![npm version](https://img.shields.io/npm/v/@subscraper/mcp.svg)](https://www.npmjs.com/package/@subscraper/mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-brightgreen.svg)](https://modelcontextprotocol.io)

Official Model Context Protocol (MCP) server for [SubScraper](https://www.subscraper.dev) — exposes all **14 Reddit data endpoints** as first-class tools for AI coding assistants and autonomous agents.

Give **Cursor**, **Claude Desktop**, **Windsurf**, **Cline**, and any [MCP-compatible](https://modelcontextprotocol.io) client live access to search Reddit, inspect community discussions, extract nested comment trees, and gather developer sentiment without OAuth setup or Reddit app approval.

---

## Quick Start

### 1. Cursor IDE

Add this to your `.cursor/mcp.json` (or global Cursor MCP configuration):

```json
{
  "mcpServers": {
    "subscraper": {
      "command": "npx",
      "args": ["-y", "@subscraper/mcp"],
      "env": {
        "SUBSCRAPER_API_KEY": "sub_live_your_key_here"
      }
    }
  }
}
```

### 2. Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "subscraper": {
      "command": "npx",
      "args": ["-y", "@subscraper/mcp"],
      "env": {
        "SUBSCRAPER_API_KEY": "sub_live_your_key_here"
      }
    }
  }
}
```

> **Note:** Get 30 free API requests immediately at [https://www.subscraper.dev](https://www.subscraper.dev).

---

## Available MCP Tools

All 14 endpoints are exposed as typed, agent-ready tools:

| Tool | Description |
|---|---|
| `search` | Search Reddit posts by keyword across all of Reddit or scoped to a subreddit |
| `get_post` | Fetch post body and the full nested comment tree pre-cleaned for LLMs |
| `get_community_posts` | Retrieve listings from any subreddit (hot, new, top, rising) with cursor pagination |
| `get_comment_permalink` | Fetch an individual comment with parent discussion context |
| `get_community_details` | Subreddit metadata, subscriber count, description, and rules |
| `get_user_profile` | User karma, account age, bio, and creator information |
| `get_user_posts` | Submission history for any public Reddit user |
| `get_user_comments` | Comment history for any public Reddit user |
| `search_communities` | Discover subreddits matching a topic or keyword |
| `search_users` | Search for Reddit usernames |
| `get_popular` | Real-time trending posts across r/popular |
| `get_leaderboard` | Top communities ranked by growth and activity |
| `explore` | Discover subreddits grouped by niche topic |
| `resolve_url_type` | Classify any Reddit link (post, comment, user, subreddit) and extract IDs |

---

## Environment Variables

| Variable | Required | Description | Default |
|---|---|---|---|
| `SUBSCRAPER_API_KEY` | ✅ Yes | Your API key from the SubScraper dashboard | — |
| `SUBSCRAPER_API_BASE_URL` | No | Override base API URL | `https://www.subscraper.dev/api/v1` |

CLI flags are also supported:
```bash
npx -y @subscraper/mcp --api-key sub_live_your_key
```

---

## Example AI Prompts

Once configured, your AI assistant can execute natural language research:

* *"Search r/SaaS for complaints about competitor pricing this month and summarize the top 5 pain points."*
* *"Fetch the top 50 comments on this Reddit URL and extract all mentioned tools: https://reddit.com/r/..."*
* *"Find the top 5 subreddits discussing local LLMs and report their subscriber counts."*
* *"Analyze the sentiment around Next.js 15 App Router across recent r/webdev discussions."*

---

## License

MIT © [SubScraper](https://www.subscraper.dev) — see [LICENSE](./LICENSE)