# Reddit MCP: the Reddit API for Claude, Cursor and any MCP client

[![npm](https://img.shields.io/npm/v/@citerocket/reddit-mcp.svg)](https://www.npmjs.com/package/@citerocket/reddit-mcp)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)

The official **[CiteRocket](https://www.citerocket.com)** MCP server, the fastest way
to use the **Reddit API** from an AI assistant. Give Claude, Cursor, or any
[Model Context Protocol](https://modelcontextprotocol.io) client direct access to
Reddit data: **search Reddit posts and comments, pull a subreddit's top, read full
comment trees, look up users and their karma, search communities, media and users,
and run shadowban checks**, all over one clean, fast, camelCase JSON API.

**Tools stay current automatically.** When CiteRocket ships a new endpoint, the new
tool shows up on your next restart, with no reinstall and no config change.

→ **[Get an API key at citerocket.com](https://app.citerocket.com)** · **[API docs](https://www.citerocket.com/docs)** · **[Rate limits](https://www.citerocket.com/docs/rate-limits)**

---

## Install

Add it to your MCP client config (Claude Desktop, Cursor, Windsurf, etc.):

```json
{
  "mcpServers": {
    "citerocket": {
      "command": "npx",
      "args": ["-y", "@citerocket/reddit-mcp@latest"],
      "env": {
        "CITEROCKET_API_KEY": "cite_live_..."
      }
    }
  }
}
```

Get your `CITEROCKET_API_KEY` from the [CiteRocket dashboard](https://app.citerocket.com).
That's all it needs.

Or via the Claude Code CLI:

```bash
claude mcp add citerocket -e CITEROCKET_API_KEY=cite_live_... -- npx -y @citerocket/reddit-mcp@latest
```

---

## What you can do

Once installed, just ask your assistant naturally:

> "Find the top posts in r/programming this week"
> "Search Reddit for posts about the new iPhone, sorted by top"
> "What's u/spez's karma and account age?"
> "Is u/some_account shadowbanned or suspended?"
> "Get the full comment tree for this post: https://reddit.com/r/..."
> "Search r/startups comments that mention 'pricing'"
> "Show me the rules and moderators of r/webdev"

---

## Tools

All tools are read-only. Query parameters are `snake_case`; responses are
camelCase JSON.

| Tool | What it does |
|------|--------------|
| `get_posts` | Fetch posts from a subreddit |
| `get_search` | Search posts across Reddit |
| `get_comments` | A post's full comment tree |
| `get_post_by_id` | Fetch one post by id |
| `get_sub_by_name_top` | A subreddit's top posts |
| `get_sub_by_name_info` | Subreddit metadata, rules, moderators |
| `get_user_by_name` | User profile and karma |
| `get_user_by_name_comments` | A user's recent comments |
| `get_user_by_name_status` | Account status / shadowban check |
| `get_search_communities` | Search communities |
| `get_search_comments` | Search comments |
| `get_search_media` | Search media |
| `get_search_users` | Search users |
| `get_cite_rocket_overview` | Your credit, usage, and billing snapshot |

The live set is whatever the server pulls from the manifest at startup, so this
table tracks what's shipped today, not a hardcoded ceiling.

---

## How billing works

Every tool call is a normal CiteRocket API call authenticated with your
`CITEROCKET_API_KEY`, metered exactly like direct API usage, no separate MCP
billing. Standard reads cost 1 credit; `get_cite_rocket_overview` is free.
Per-plan QPS ceilings apply, see the [rate limits](https://www.citerocket.com/docs/rate-limits).

---

## Configuration

| Env var | Required | Purpose |
|---------|----------|---------|
| `CITEROCKET_API_KEY` | yes | Your API key, sent as `Authorization: Bearer` on every call. |

If CiteRocket is briefly unreachable at startup, the server falls back to the tool
set bundled in the package so your existing tools keep working.

---

## Development

```bash
npm install
npm run build:manifest   # regenerate the bundled tool manifest from the OpenAPI spec
npm run build            # compile TypeScript to dist/
```

---

## Links

- 🌐 **Website:** [citerocket.com](https://www.citerocket.com)
- 📚 **API docs:** [citerocket.com/docs](https://www.citerocket.com/docs)
- 🔑 **Get an API key:** [app.citerocket.com](https://app.citerocket.com)
- 📈 **Status:** [citerocket.com/status](https://www.citerocket.com/status)
- ✉️ **Support:** [support@citerocket.com](mailto:support@citerocket.com)

CiteRocket is an independent third-party API for developers and researchers. Not
affiliated with, endorsed by, or sponsored by Reddit, Inc.

## License

MIT