redditapis-mcp 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0
+- Initial release: 11 read tools over the redditapis.com API (subreddit listings,
+  post/comment/community/user/media search, comment tree, subreddit top posts,
+  user profile + comments). Stdio transport, Bearer auth, per-request timeout.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 redditapis.com
+
+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.

package/README.md

@@ -0,0 +1,69 @@
+# redditapis-mcp
+
+Official [Model Context Protocol](https://modelcontextprotocol.io) server for
+**[redditapis.com](https://www.redditapis.com)** — the Reddit API as native tools
+for Claude, Cursor, and any MCP client.
+
+It exposes Reddit reads as typed tools: subreddit listings, post / comment /
+community / user / media search, a post's full comment tree, subreddit top posts,
+and user profile + comments. Each tool is a thin, stateless wrapper over a REST
+endpoint at `https://api.redditapis.com`; your API key is forwarded on every call.
+
+## Setup
+
+Get an API key at [redditapis.com](https://www.redditapis.com), then add the
+server to your MCP client. It runs over stdio via `npx` (no install needed):
+
+### Claude Desktop / Claude Code / Cursor (`mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "reddit": {
+      "command": "npx",
+      "args": ["-y", "redditapis-mcp@latest"],
+      "env": { "REDDITAPIS_KEY": "your_api_key_here" }
+    }
+  }
+}
+```
+
+## Configuration (env)
+
+| Variable | Required | Default | Notes |
+|---|---|---|---|
+| `REDDITAPIS_KEY` | yes | — | Your key. `REDDIT_APIS_KEY` is accepted as an alias. |
+| `REDDITAPIS_BASE_URL` | no | `https://api.redditapis.com` | Override the API base. |
+| `REDDITAPIS_TIMEOUT_MS` | no | `30000` | Per-request timeout in ms. |
+
+## Tools
+
+All tools are **read-only**. Reddit writes (comment / vote / DM) are a separate
+authenticated surface and are intentionally not exposed here.
+
+| Tool | Endpoint | What it does |
+|---|---|---|
+| `reddit_subreddit_posts` | `GET /api/reddit/posts` | List a subreddit's posts by sort (hot/new/top/rising/…) |
+| `reddit_search` | `GET /api/reddit/search` | Search posts across Reddit or one subreddit |
+| `reddit_post_comments` | `GET /api/reddit/comments` | A post + its comment tree, by permalink |
+| `reddit_search_communities` | `GET /api/reddit/search/communities` | Find subreddits by name/topic |
+| `reddit_search_comments` | `GET /api/reddit/search/comments` | Search comments (not posts) |
+| `reddit_search_media` | `GET /api/reddit/search/media` | Search image/video/gif posts |
+| `reddit_search_users` | `GET /api/reddit/search/users` | Find redditors by name |
+| `reddit_subreddit_top` | `GET /api/reddit/sub/{name}/top` | Top posts of a subreddit for a time window |
+| `reddit_post` | `GET /api/reddit/post/{id}` | A single post by id |
+| `reddit_user_profile` | `GET /api/reddit/user/{name}` | A user's public profile |
+| `reddit_user_comments` | `GET /api/reddit/user/{name}/comments` | A user's recent comments |
+
+## Development
+
+```bash
+npm install
+npm run check   # syntax check both source files
+npm test        # unit-test the tool catalog + query/path builders (no network)
+npm start       # run the stdio server (needs REDDITAPIS_KEY)
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "redditapis-mcp",
+  "version": "0.1.1",
+  "description": "Official MCP server for redditapis.com, the Reddit API (subreddit listings, post + comment + community + user + media search, comment trees, top posts, user profiles) as native tools for Claude, Cursor, and any MCP client.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/redditapis/redditapis-mcp.git"
+  },
+  "type": "module",
+  "bin": {
+    "reddit-mcp": "src/index.js",
+    "redditapis-mcp": "src/index.js"
+  },
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "check": "node --check src/index.js && node --check src/tools.js",
+    "test": "node test/tools.test.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.8 || ^4.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "reddit",
+    "reddit-api",
+    "claude",
+    "cursor",
+    "redditapis"
+  ],
+  "author": "redditapis.com",
+  "license": "MIT",
+  "homepage": "https://www.redditapis.com",
+  "bugs": {
+    "url": "https://github.com/redditapis/redditapis-mcp/issues"
+  }
+}

package/src/index.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// redditapis-mcp, official MCP server for redditapis.com
+//
+// Exposes the Reddit API as native MCP tools for Claude, Cursor, and any MCP
+// client: subreddit listings, post + comment search, community/user/media/comment
+// search, a post's comment tree, subreddit top posts, and user profile/comments.
+// Each tool is a thin, typed wrapper over a REST endpoint at
+// https://api.redditapis.com. The server holds no state and forwards your API
+// key on every call. The tool catalog lives in ./tools.js.
+//
+// Config (env):
+//   REDDITAPIS_KEY        required. Your key from https://www.redditapis.com
+//                         (REDDIT_APIS_KEY is accepted as an alias).
+//   REDDITAPIS_BASE_URL   optional. Defaults to https://api.redditapis.com
+//   REDDITAPIS_TIMEOUT_MS optional. Per-request timeout (default 30000)
+//
+// Run:  npx -y redditapis-mcp@latest   (stdio transport)
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { TOOLS, buildQuery, buildPath } from "./tools.js";
+
+const API_KEY = process.env.REDDITAPIS_KEY || process.env.REDDIT_APIS_KEY;
+const BASE_URL = (
+  process.env.REDDITAPIS_BASE_URL || "https://api.redditapis.com"
+).replace(/\/+$/, "");
+const REQUEST_TIMEOUT_MS = Number(process.env.REDDITAPIS_TIMEOUT_MS || 30000);
+const VERSION = "0.1.0";
+
+if (!API_KEY) {
+  console.error(
+    "[reddit-mcp] Missing REDDITAPIS_KEY. Get a key at https://www.redditapis.com and set it in your MCP client config.",
+  );
+  process.exit(1);
+}
+
+// REST call. Resolves any {param} path placeholders from args, sends the rest as
+// the query string, and forwards the API key as a Bearer token (redditapis.com
+// authenticates via `Authorization: Bearer <key>` only).
+async function callEndpoint(pathTemplate, args, method = "GET") {
+  const { path, rest } = buildPath(pathTemplate, args);
+  const q = buildQuery(rest);
+  const url = `${BASE_URL}${path}${q ? `?${q}` : ""}`;
+
+  const headers = {
+    Authorization: `Bearer ${API_KEY}`,
+    accept: "application/json",
+    "user-agent": `reddit-mcp/${VERSION}`,
+  };
+
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, { method, headers, signal: ctrl.signal });
+    const body = await res.text();
+    if (!res.ok) {
+      const hint =
+        res.status === 401
+          ? " (invalid or missing API key, verify REDDITAPIS_KEY at https://www.redditapis.com)"
+          : res.status === 402
+            ? " (insufficient credits, top up at https://www.redditapis.com)"
+            : res.status === 403
+              ? " (access forbidden. The subreddit/user may be private, banned, or quarantined)"
+              : res.status === 404
+                ? " (not found. The subreddit, post id, user, or permalink may be wrong or deleted)"
+                : res.status === 429
+                  ? " (rate limited. Wait a few seconds and retry, or reduce request frequency)"
+                  : res.status >= 500
+                    ? " (upstream API error. Retry in a moment; if persistent, contact https://www.redditapis.com)"
+                    : "";
+      return { isError: true, content: [{ type: "text", text: `HTTP ${res.status}${hint}: ${body.slice(0, 1200)}` }] };
+    }
+    return { content: [{ type: "text", text: body }] };
+  } catch (err) {
+    const msg = err?.name === "AbortError" ? `timed out after ${REQUEST_TIMEOUT_MS}ms` : err?.message || String(err);
+    return { isError: true, content: [{ type: "text", text: `Request failed: ${msg}` }] };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+const server = new McpServer({ name: "redditapis", version: VERSION });
+
+for (const tool of TOOLS) {
+  const method = tool.method || "GET";
+  const annotations = {
+    title: tool.name,
+    readOnlyHint: !tool.write, // every tool here is a read
+    destructiveHint: Boolean(tool.destructive),
+    openWorldHint: true,
+  };
+  server.registerTool(
+    tool.name,
+    { description: tool.description, inputSchema: tool.shape, annotations },
+    async (args) => callEndpoint(tool.path, args, method),
+  );
+}
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  // Logs go to stderr so they never corrupt the stdio JSON-RPC stream.
+  console.error(`[reddit-mcp] ready · ${TOOLS.length} tools · base ${BASE_URL}`);
+}
+
+main().catch((err) => {
+  console.error("[reddit-mcp] fatal:", err);
+  process.exit(1);
+});

package/src/tools.js

@@ -0,0 +1,215 @@
+// Tool catalog + pure query/path builders for redditapis-mcp.
+// Kept separate from the server wiring (index.js) so it can be unit-tested
+// without spawning the stdio transport.
+//
+// Each tool maps 1:1 to a REST endpoint at https://api.redditapis.com/api/reddit.
+// Tool arg names map 1:1 to endpoint query params, EXCEPT path params written as
+// {name}/{id} in a tool's `path` (e.g. /api/reddit/sub/{name}/top), which are
+// interpolated into the URL and removed from the query string. Every tool here
+// is a READ (GET); reddit writes (comment/vote/DM) are a separate authenticated
+// surface and are intentionally out of scope for this reads MCP.
+import { z } from "zod";
+
+// Shared Zod input-schema fragments.
+const LIMIT = {
+  limit: z.number().int().min(1).max(100).optional().describe(
+    "Max items to return (1 to 100). The API clamps out-of-range values; endpoint default applies if omitted.",
+  ),
+};
+const AFTER = {
+  after: z.string().optional().describe(
+    "Opaque Reddit pagination cursor from the previous response's `after` field (a fullname like `t3_abc123`). Omit on the first call; pass it to fetch the next page.",
+  ),
+};
+// Sort vocabularies differ by endpoint (they map to different Reddit listings):
+// posts/listings, search, and user-comments each accept a distinct set.
+const SORT_POSTS = {
+  sort: z.enum(["new", "hot", "top", "rising", "controversial", "best"]).optional().describe(
+    "Sort order for a subreddit listing. 'hot' = trending now, 'new' = most recent (default), 'top' = highest score in the `t` window, 'rising' = gaining fast, 'controversial' = polarizing, 'best' = Reddit's blended rank.",
+  ),
+};
+const SORT_SEARCH = {
+  sort: z.enum(["relevance", "hot", "top", "new", "comments"]).optional().describe(
+    "Sort order for search. 'relevance' = best match (default), 'top' = highest score in the `t` window, 'new' = most recent, 'hot' = trending, 'comments' = most-discussed.",
+  ),
+};
+const SORT_USER = {
+  sort: z.enum(["new", "hot", "top", "controversial"]).optional().describe(
+    "Sort order for a user's comments. 'new' = most recent (default), 'hot', 'top' (in the `t` window), 'controversial'.",
+  ),
+};
+const TIME = {
+  t: z.enum(["hour", "day", "week", "month", "year", "all"]).optional().describe(
+    "Time window, only applied when sort is 'top' or 'controversial'. E.g. 'week' = top of the past week. Ignored for other sorts.",
+  ),
+};
+const NSFW = {
+  nsfw: z.enum(["true", "false"]).optional().describe(
+    "Set 'true' to include over-18 / NSFW results. Omit or 'false' to exclude them (default).",
+  ),
+};
+const QUERY = {
+  q: z.string().min(1).describe(
+    "Search query text. Supports Reddit search syntax (e.g. `subreddit:webdev`, `author:spez`, `\"exact phrase\"`, `title:...`).",
+  ),
+};
+
+// The tool catalog. All reads (GET). Path params are {name}/{id} placeholders.
+export const TOOLS = [
+  {
+    name: "reddit_subreddit_posts",
+    path: "/api/reddit/posts",
+    description:
+      "List posts from a subreddit by sort order. Use this to read a community's feed: newest, hot/trending, top-of-week, rising, etc. Returns post title, author, score, comment count, permalink, flair, and media, plus an `after` cursor for paging. Example: subreddit='programming' sort='top' t='week'.",
+    shape: {
+      subreddit: z.string().min(1).describe(
+        "Subreddit name WITHOUT the r/ prefix (e.g. 'programming', 'AskReddit'). Required.",
+      ),
+      ...SORT_POSTS,
+      ...TIME,
+      ...AFTER,
+      ...LIMIT,
+    },
+  },
+  {
+    name: "reddit_search",
+    path: "/api/reddit/search",
+    description:
+      "Search Reddit posts across all of Reddit or within one subreddit. Returns matching posts with author, score, comments, permalink, and an `after` cursor. Use for topic/keyword research, brand monitoring, or finding discussions. Scope to a community with `subreddit`. Example: q='rust vs go' sort='top' t='year'.",
+    shape: {
+      ...QUERY,
+      subreddit: z.string().optional().describe(
+        "Optional subreddit name (without r/) to restrict the search to one community. Omit to search all of Reddit.",
+      ),
+      ...SORT_SEARCH,
+      ...TIME,
+      ...AFTER,
+      ...NSFW,
+      ...LIMIT,
+    },
+  },
+  {
+    name: "reddit_post_comments",
+    path: "/api/reddit/comments",
+    description:
+      "Fetch a single post and its comment tree by permalink. Returns the post plus threaded comments (author, body, score, replies) and an `after` cursor. Use after finding a post via search/listing to read the full discussion. Pass the post's `permalink` from a prior result.",
+    shape: {
+      permalink: z.string().min(1).describe(
+        "The post permalink path from a prior post result, e.g. '/r/programming/comments/abc123/some_title/'. Required.",
+      ),
+    },
+  },
+  {
+    name: "reddit_search_communities",
+    path: "/api/reddit/search/communities",
+    description:
+      "Search for subreddits (communities) by name or topic. Returns matching subreddits with title, subscriber count, description, and NSFW flag. Use to discover where a topic is discussed before listing or searching its posts. Example: q='machine learning'.",
+    shape: { ...QUERY, ...AFTER, ...NSFW, ...LIMIT },
+  },
+  {
+    name: "reddit_search_comments",
+    path: "/api/reddit/search/comments",
+    description:
+      "Search Reddit COMMENTS (not posts) by keyword across Reddit. Returns matching comments with author, body, score, subreddit, and the parent post link. Use to find first-hand opinions/answers buried in threads. Example: q='best mechanical keyboard' sort='top'.",
+    shape: { ...QUERY, ...SORT_SEARCH, ...TIME, ...AFTER, ...NSFW, ...LIMIT },
+  },
+  {
+    name: "reddit_search_media",
+    path: "/api/reddit/search/media",
+    description:
+      "Search Reddit posts filtered to media (images, video, gifs). Returns media posts with the media URL/type, author, score, and permalink. Use `kind` to narrow to a media type. Example: q='aurora borealis' kind='image'.",
+    shape: {
+      ...QUERY,
+      kind: z.enum(["image", "video", "gif", "all"]).optional().describe(
+        "Media type filter. 'image', 'video', 'gif', or 'all' (default). Filters the raw Reddit results to that media kind.",
+      ),
+      ...SORT_SEARCH,
+      ...TIME,
+      ...AFTER,
+      ...NSFW,
+      ...LIMIT,
+    },
+  },
+  {
+    name: "reddit_search_users",
+    path: "/api/reddit/search/users",
+    description:
+      "Search for Reddit users (redditors) by name or keyword. Returns matching accounts with username, karma, and account age. Use to find a person's handle before fetching their profile or comments. Example: q='spez'.",
+    shape: { ...QUERY, ...AFTER, ...NSFW, ...LIMIT },
+  },
+  {
+    name: "reddit_subreddit_top",
+    path: "/api/reddit/sub/{name}/top",
+    description:
+      "Get the TOP posts of a subreddit for a time window. Shorthand for the highest-scoring posts of a community. Returns posts with score, author, comments, and permalink plus an `after` cursor. Example: name='science' t='month'.",
+    shape: {
+      name: z.string().min(1).describe(
+        "Subreddit name WITHOUT the r/ prefix (e.g. 'science'). Required (path parameter).",
+      ),
+      ...TIME,
+      ...AFTER,
+      ...LIMIT,
+    },
+  },
+  {
+    name: "reddit_post",
+    path: "/api/reddit/post/{id}",
+    description:
+      "Fetch a single Reddit post by its id. Returns the full post object (title, author, score, body/selftext, media, permalink, subreddit). Use when you already have a post id and want its details. Example: id='abc123' (the base-36 id, no t3_ prefix).",
+    shape: {
+      id: z.string().min(1).describe(
+        "The post's base-36 id (e.g. 'abc123'), without the 't3_' fullname prefix. Required (path parameter).",
+      ),
+    },
+  },
+  {
+    name: "reddit_user_profile",
+    path: "/api/reddit/user/{name}",
+    description:
+      "Fetch a Reddit user's public profile by username. Returns account info: username, id, karma (post + comment), account age, verified/employee flags, and avatar. Use to vet or summarize a redditor. Example: name='spez'.",
+    shape: {
+      name: z.string().min(1).describe(
+        "Reddit username WITHOUT the u/ prefix (e.g. 'spez'). Required (path parameter).",
+      ),
+    },
+  },
+  {
+    name: "reddit_user_comments",
+    path: "/api/reddit/user/{name}/comments",
+    description:
+      "List a Reddit user's recent comments. Returns comments with body, score, subreddit, parent link, and timestamp plus an `after` cursor. Use to understand what a redditor talks about or to gather their opinions. Example: name='spez' sort='top'.",
+    shape: {
+      name: z.string().min(1).describe(
+        "Reddit username WITHOUT the u/ prefix (e.g. 'spez'). Required (path parameter).",
+      ),
+      ...SORT_USER,
+      ...AFTER,
+      ...LIMIT,
+    },
+  },
+];
+
+// Turn tool args into a URL query string. Skips undefined/null/empty values.
+export function buildQuery(args) {
+  const qs = new URLSearchParams();
+  for (const [k, v] of Object.entries(args || {})) {
+    if (v !== undefined && v !== null && String(v).length > 0) qs.set(k, String(v));
+  }
+  return qs.toString();
+}
+
+// Interpolate {param} path placeholders from args; return the resolved path and
+// the remaining args (which become the query string). A missing path param is
+// left empty (the endpoint then 404s, surfaced to the caller) rather than
+// throwing, so one bad call never crashes the server.
+export function buildPath(template, args) {
+  const used = new Set();
+  const path = String(template).replace(/\{(\w+)\}/g, (_, k) => {
+    used.add(k);
+    const v = args?.[k];
+    return encodeURIComponent(v == null ? "" : String(v));
+  });
+  const rest = {};
+  for (const [k, v] of Object.entries(args || {})) if (!used.has(k)) rest[k] = v;
+  return { path, rest };
+}