@unclick/reddit-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+Apache License 2.0
+
+Copyright (c) 2026 UnClick / malamutemayhem
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,39 @@
+# Reddit MCP by UnClick
+
+Search, read, and post across Reddit: posts, comments, subreddits, and users.
+
+> By UnClick. 180+ tools plus persistent agent memory in one install: https://unclick.world
+
+## Install
+
+Installs straight from GitHub, no npm account needed.
+
+```json
+{
+  "mcpServers": {
+    "reddit": {
+      "command": "npx",
+      "args": ["-y", "https://github.com/malamutemayhem/unclick/releases/download/standalone-mcps-latest/reddit.tgz"]
+    }
+  }
+}
+```
+
+## Tools
+
+- `reddit_read`
+- `reddit_post`
+- `reddit_comment`
+- `reddit_search`
+- `reddit_user`
+- `reddit_vote`
+- `reddit_subscribe`
+
+## Want the rest?
+
+This is one connector. [UnClick](https://unclick.world) bundles 180+ tools plus
+persistent cross-session agent memory in a single install.
+
+## License
+
+Apache-2.0

package/dist/index.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+// Reddit MCP. Standalone MCP server by UnClick.
+// By UnClick. 180+ tools plus persistent agent memory in one install: https://unclick.world
+//
+// Generated from the UnClick connector by scripts/generate-standalone-mcp.mjs.
+// Edit the connector in the UnClick monorepo, not here.
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { redditRead, redditPost, redditComment, redditSearch, redditUser, redditVote, redditSubscribe, } from "./reddit-tool.js";
+const TOOLS = [
+    {
+        name: "reddit_read",
+        description: "Read posts from a Reddit subreddit.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                access_token: { type: "string" },
+                subreddit: { type: "string" },
+                sort: { type: "string", enum: ["hot", "new", "top", "rising"], description: "hot, new, top, rising" },
+                limit: { type: "number" },
+                after: { type: "string" },
+                t: { type: "string", enum: ["hour", "day", "week", "month", "year", "all"], description: "hour, day, week, month, year, all" },
+            },
+            required: ["access_token", "subreddit"],
+        },
+    },
+    {
+        name: "reddit_post",
+        description: "Create a Reddit post.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                access_token: { type: "string" },
+                subreddit: { type: "string" },
+                title: { type: "string" },
+                kind: { type: "string", enum: ["self", "link"], description: "self, link" },
+                text: { type: "string" },
+                url: { type: "string" },
+                nsfw: { type: "boolean" },
+                spoiler: { type: "boolean" },
+            },
+            required: ["access_token", "subreddit", "title", "kind"],
+        },
+    },
+    {
+        name: "reddit_comment",
+        description: "Post a comment on Reddit.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                access_token: { type: "string" },
+                parent_id: { type: "string" },
+                text: { type: "string" },
+            },
+            required: ["access_token", "parent_id", "text"],
+        },
+    },
+    {
+        name: "reddit_search",
+        description: "Search Reddit posts.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                access_token: { type: "string" },
+                q: { type: "string" },
+                subreddit: { type: "string" },
+                sort: { type: "string" },
+                limit: { type: "number" },
+            },
+            required: ["access_token", "q"],
+        },
+    },
+    {
+        name: "reddit_user",
+        description: "Get a Reddit user profile and posts.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                access_token: { type: "string" },
+                username: { type: "string" },
+                type: { type: "string", description: "overview, submitted, comments" },
+                limit: { type: "number" },
+            },
+            required: ["access_token", "username"],
+        },
+    },
+    {
+        name: "reddit_vote",
+        description: "Vote on a Reddit post or comment.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                access_token: { type: "string" },
+                id: { type: "string" },
+                dir: { type: "number", description: "1=upvote, 0=neutral, -1=downvote" },
+            },
+            required: ["access_token", "id", "dir"],
+        },
+    },
+    {
+        name: "reddit_subscribe",
+        description: "Subscribe to or unsubscribe from a Reddit subreddit.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                access_token: { type: "string" },
+                sr: { type: "string" },
+                action: { type: "string", enum: ["sub", "unsub"], description: "sub or unsub" },
+            },
+            required: ["access_token", "sr", "action"],
+        },
+    }
+];
+const HANDLERS = {
+    reddit_read: (args) => redditRead(args),
+    reddit_post: (args) => redditPost(args),
+    reddit_comment: (args) => redditComment(args),
+    reddit_search: (args) => redditSearch(args),
+    reddit_user: (args) => redditUser(args),
+    reddit_vote: (args) => redditVote(args),
+    reddit_subscribe: (args) => redditSubscribe(args),
+};
+const server = new Server({ name: "io.github.malamutemayhem/reddit", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const handler = HANDLERS[req.params.name];
+    if (!handler) {
+        return { content: [{ type: "text", text: `Unknown tool: ${req.params.name}` }], isError: true };
+    }
+    try {
+        const result = await handler((req.params.arguments ?? {}));
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: message }], isError: true };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`[reddit-mcp] fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/reddit-tool.js

@@ -0,0 +1,347 @@
+// Reddit API MCP Tool
+// Connects to Reddit via OAuth2 bearer tokens (oauth.reddit.com).
+// No external dependencies - uses global fetch (Node 18+).
+// Rate limit: Reddit allows 60 requests/minute for OAuth clients.
+const REDDIT_BASE = "https://oauth.reddit.com";
+const USER_AGENT = "UnClick-MCP/1.0 by unclick.dev";
+// Per-process rate limit tracking (headers from Reddit responses)
+let _remaining = 60;
+let _resetAt = Date.now() + 60_000;
+// ── Internal fetch helper ────────────────────────────────────────────────────
+async function rFetch(method, path, accessToken, body) {
+    // Guard: if we have no remaining quota and reset hasn't passed, bail early
+    if (_remaining <= 0 && Date.now() < _resetAt) {
+        const waitMs = _resetAt - Date.now();
+        return {
+            error: "rate_limited",
+            message: `Reddit rate limit reached. Resets in ${Math.ceil(waitMs / 1000)}s.`,
+            retry_after_ms: waitMs,
+        };
+    }
+    const headers = {
+        Authorization: `Bearer ${accessToken}`,
+        "User-Agent": USER_AGENT,
+    };
+    let url = `${REDDIT_BASE}${path}`;
+    let fetchBody;
+    if (method === "GET" && body) {
+        const qs = new URLSearchParams(Object.fromEntries(Object.entries(body).map(([k, v]) => [k, String(v)]))).toString();
+        url = `${url}?${qs}`;
+    }
+    else if (method === "POST" && body) {
+        headers["Content-Type"] = "application/x-www-form-urlencoded";
+        fetchBody = new URLSearchParams(Object.fromEntries(Object.entries(body).map(([k, v]) => [k, String(v)]))).toString();
+    }
+    const res = await fetch(url, { method, headers, body: fetchBody });
+    // Update rate limit state from response headers
+    const rem = res.headers.get("x-ratelimit-remaining");
+    const rst = res.headers.get("x-ratelimit-reset");
+    if (rem !== null)
+        _remaining = parseFloat(rem);
+    if (rst !== null)
+        _resetAt = Date.now() + parseFloat(rst) * 1_000;
+    if (res.status === 429) {
+        const retryAfter = res.headers.get("retry-after");
+        return {
+            error: "rate_limited",
+            message: "Reddit API rate limit exceeded.",
+            retry_after_seconds: retryAfter ? Number(retryAfter) : 60,
+        };
+    }
+    if (res.status === 401) {
+        return {
+            error: "unauthorized",
+            message: "Invalid or expired access token. Re-authenticate via Reddit OAuth2.",
+        };
+    }
+    if (res.status === 403) {
+        return {
+            error: "forbidden",
+            message: "Access denied. Check token scopes or subreddit permissions.",
+        };
+    }
+    if (res.status === 404) {
+        return { error: "not_found", message: `Resource not found: ${path}` };
+    }
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        return { error: `http_${res.status}`, message: text || res.statusText };
+    }
+    const json = await res.json();
+    // Reddit wraps API errors in { error: ..., message: ... }
+    if (json && typeof json === "object" && "error" in json) {
+        return { error: json["error"], message: json["message"] };
+    }
+    return json;
+}
+// ── Shape helpers ────────────────────────────────────────────────────────────
+function shapePosts(listing) {
+    if (!listing ||
+        typeof listing !== "object" ||
+        !("data" in listing))
+        return [];
+    const data = listing["data"];
+    const children = Array.isArray(data?.["children"]) ? data["children"] : [];
+    return children.map((child) => {
+        const d = (child["data"] ?? {});
+        return {
+            id: d["id"],
+            name: d["name"],
+            title: d["title"],
+            author: d["author"],
+            subreddit: d["subreddit"],
+            score: d["score"],
+            upvote_ratio: d["upvote_ratio"],
+            num_comments: d["num_comments"],
+            url: d["url"],
+            permalink: d["permalink"] ? `https://reddit.com${d["permalink"]}` : null,
+            selftext: d["selftext"] ?? null,
+            is_self: d["is_self"],
+            created_utc: d["created_utc"],
+            nsfw: d["over_18"],
+            spoiler: d["spoiler"],
+            flair: d["link_flair_text"] ?? null,
+        };
+    });
+}
+function shapeComments(listing) {
+    if (!listing ||
+        typeof listing !== "object" ||
+        !("data" in listing))
+        return [];
+    const data = listing["data"];
+    const children = Array.isArray(data?.["children"]) ? data["children"] : [];
+    return children
+        .filter((c) => {
+        const kind = c["kind"];
+        return kind === "t1";
+    })
+        .map((child) => {
+        const d = (child["data"] ?? {});
+        return {
+            id: d["id"],
+            name: d["name"],
+            author: d["author"],
+            body: d["body"],
+            score: d["score"],
+            created_utc: d["created_utc"],
+            permalink: d["permalink"] ? `https://reddit.com${d["permalink"]}` : null,
+            parent_id: d["parent_id"],
+            subreddit: d["subreddit"],
+        };
+    });
+}
+export async function redditRead(args) {
+    const sub = args.subreddit.replace(/^r\//i, "");
+    const sort = args.sort ?? "hot";
+    const limit = Math.min(100, Math.max(1, Number(args.limit ?? 25)));
+    const params = { limit };
+    if (args.after)
+        params["after"] = args.after;
+    if (sort === "top" && args.t)
+        params["t"] = args.t;
+    const result = await rFetch("GET", `/r/${sub}/${sort}.json`, args.access_token, params);
+    if (result && typeof result === "object" && "error" in result)
+        return result;
+    const posts = shapePosts(result);
+    const data = result?.["data"];
+    return {
+        subreddit: sub,
+        sort,
+        count: posts.length,
+        after: data?.["after"] ?? null,
+        before: data?.["before"] ?? null,
+        posts,
+    };
+}
+export async function redditPost(args) {
+    const sub = args.subreddit.replace(/^r\//i, "");
+    if (!args.title?.trim())
+        return { error: "validation", message: "title is required." };
+    if (args.kind === "self" && !args.text)
+        return { error: "validation", message: "text is required for self posts." };
+    if (args.kind === "link" && !args.url)
+        return { error: "validation", message: "url is required for link posts." };
+    const body = {
+        sr: sub,
+        title: args.title,
+        kind: args.kind,
+        api_type: "json",
+        resubmit: true,
+        nsfw: args.nsfw ?? false,
+        spoiler: args.spoiler ?? false,
+    };
+    if (args.kind === "self")
+        body["text"] = args.text;
+    if (args.kind === "link")
+        body["url"] = args.url;
+    if (args.flair_id)
+        body["flair_id"] = args.flair_id;
+    if (args.flair_text)
+        body["flair_text"] = args.flair_text;
+    const result = await rFetch("POST", "/api/submit", args.access_token, body);
+    if (result && typeof result === "object" && "error" in result)
+        return result;
+    // Reddit wraps submit response in json.data
+    const json = result?.["json"];
+    const errors = json?.["errors"];
+    if (errors && errors.length > 0) {
+        return { error: "submit_error", errors };
+    }
+    const postData = json?.["data"];
+    return {
+        success: true,
+        id: postData?.["id"],
+        name: postData?.["name"],
+        url: postData?.["url"],
+    };
+}
+export async function redditComment(args) {
+    if (!args.parent_id?.trim())
+        return { error: "validation", message: "parent_id is required (e.g. t3_abc123 or t1_def456)." };
+    if (!args.text?.trim())
+        return { error: "validation", message: "text is required." };
+    const body = {
+        parent: args.parent_id,
+        text: args.text,
+        api_type: "json",
+    };
+    const result = await rFetch("POST", "/api/comment", args.access_token, body);
+    if (result && typeof result === "object" && "error" in result)
+        return result;
+    const json = result?.["json"];
+    const errors = json?.["errors"];
+    if (errors && errors.length > 0) {
+        return { error: "comment_error", errors };
+    }
+    const things = json?.["data"]?.["things"];
+    const first = things?.[0];
+    const d = (first?.["data"] ?? {});
+    return {
+        success: true,
+        id: d["id"],
+        name: d["name"],
+        author: d["author"],
+        body: d["body"],
+        created_utc: d["created_utc"],
+        permalink: d["permalink"] ? `https://reddit.com${d["permalink"]}` : null,
+    };
+}
+export async function redditSearch(args) {
+    if (!args.query?.trim())
+        return { error: "validation", message: "query is required." };
+    const limit = Math.min(100, Math.max(1, Number(args.limit ?? 25)));
+    const params = {
+        q: args.query,
+        sort: args.sort ?? "relevance",
+        limit,
+        type: "link",
+    };
+    if (args.t)
+        params["t"] = args.t;
+    if (args.after)
+        params["after"] = args.after;
+    if (args.subreddit)
+        params["restrict_sr"] = true;
+    const sub = args.subreddit?.replace(/^r\//i, "");
+    const path = sub ? `/r/${sub}/search.json` : "/search.json";
+    const result = await rFetch("GET", path, args.access_token, params);
+    if (result && typeof result === "object" && "error" in result)
+        return result;
+    const posts = shapePosts(result);
+    const data = result?.["data"];
+    return {
+        query: args.query,
+        subreddit: sub ?? null,
+        sort: args.sort ?? "relevance",
+        count: posts.length,
+        after: data?.["after"] ?? null,
+        results: posts,
+    };
+}
+export async function redditUser(args) {
+    const username = args.username.replace(/^u\//i, "");
+    if (!username)
+        return { error: "validation", message: "username is required." };
+    const limit = Math.min(100, Math.max(1, Number(args.limit ?? 10)));
+    const [aboutResult, ...activityResults] = await Promise.all([
+        rFetch("GET", `/user/${username}/about.json`, args.access_token),
+        args.include_posts !== false
+            ? rFetch("GET", `/user/${username}/submitted.json`, args.access_token, { limit })
+            : Promise.resolve(null),
+        args.include_comments !== false
+            ? rFetch("GET", `/user/${username}/comments.json`, args.access_token, { limit })
+            : Promise.resolve(null),
+    ]);
+    if (aboutResult && typeof aboutResult === "object" && "error" in aboutResult) {
+        return aboutResult;
+    }
+    const userData = (aboutResult?.["data"] ?? {});
+    const profile = {
+        id: userData["id"],
+        name: userData["name"],
+        created_utc: userData["created_utc"],
+        link_karma: userData["link_karma"],
+        comment_karma: userData["comment_karma"],
+        is_verified: userData["verified"],
+        is_mod: userData["is_mod"],
+        icon_img: userData["icon_img"],
+        snoovatar_img: userData["snoovatar_img"],
+        subreddit: userData["subreddit"]
+            ? {
+                display_name: userData["subreddit"]?.["display_name"],
+                public_description: userData["subreddit"]?.["public_description"],
+                subscribers: userData["subreddit"]?.["subscribers"],
+            }
+            : null,
+    };
+    const [postsResult, commentsResult] = activityResults;
+    const result = { profile };
+    if (postsResult && !(typeof postsResult === "object" && "error" in postsResult)) {
+        result["recent_posts"] = shapePosts(postsResult);
+    }
+    if (commentsResult && !(typeof commentsResult === "object" && "error" in commentsResult)) {
+        result["recent_comments"] = shapeComments(commentsResult);
+    }
+    return result;
+}
+export async function redditVote(args) {
+    if (!args.id?.trim())
+        return { error: "validation", message: "id (fullname) is required, e.g. t3_abc123." };
+    const dir = Number(args.dir);
+    if (dir !== 1 && dir !== 0 && dir !== -1) {
+        return { error: "validation", message: "dir must be 1 (upvote), 0 (remove vote), or -1 (downvote)." };
+    }
+    const result = await rFetch("POST", "/api/vote", args.access_token, {
+        id: args.id,
+        dir,
+    });
+    if (result && typeof result === "object" && "error" in result)
+        return result;
+    return {
+        success: true,
+        id: args.id,
+        dir,
+        action: dir === 1 ? "upvoted" : dir === -1 ? "downvoted" : "vote_removed",
+    };
+}
+export async function redditSubscribe(args) {
+    const sub = args.subreddit.replace(/^r\//i, "");
+    if (!sub)
+        return { error: "validation", message: "subreddit is required." };
+    if (args.action !== "sub" && args.action !== "unsub") {
+        return { error: "validation", message: "action must be 'sub' or 'unsub'." };
+    }
+    // Fetch subreddit info to get the fullname (sr_name param is also accepted)
+    const result = await rFetch("POST", "/api/subscribe", args.access_token, {
+        action: args.action,
+        sr_name: sub,
+    });
+    if (result && typeof result === "object" && "error" in result)
+        return result;
+    return {
+        success: true,
+        subreddit: sub,
+        action: args.action === "sub" ? "subscribed" : "unsubscribed",
+    };
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@unclick/reddit-mcp",
+  "version": "0.1.0",
+  "mcpName": "io.github.malamutemayhem/reddit",
+  "description": "Search, read, and post across Reddit: posts, comments, subreddits, and users. By UnClick (https://unclick.world).",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "unclick",
+    "reddit",
+    "social",
+    "forums",
+    "subreddit"
+  ],
+  "author": "UnClick (https://unclick.world)",
+  "type": "module",
+  "bin": {
+    "reddit-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "server.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.15.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/malamutemayhem/unclick.git",
+    "directory": "packages/standalone/reddit-mcp"
+  },
+  "homepage": "https://unclick.world"
+}

package/server.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.malamutemayhem/reddit",
+  "title": "Reddit MCP by UnClick",
+  "description": "Search, read, and post across Reddit: posts, comments, subreddits, and users. By UnClick.",
+  "version": "0.1.0",
+  "websiteUrl": "https://unclick.world",
+  "icons": [
+    {
+      "src": "https://unclick.world/favicon.png",
+      "mimeType": "image/png",
+      "sizes": [
+        "512x512"
+      ]
+    }
+  ],
+  "repository": {
+    "url": "https://github.com/malamutemayhem/unclick.git",
+    "source": "github",
+    "subfolder": "packages/standalone/reddit-mcp"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@unclick/reddit-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "npx",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}