Reddit MCP Buddy

Reddit MCP Buddy

面向 Claude Desktop 和 AI 助手的 Reddit 浏览器

一个用于浏览 Reddit、搜索帖子和分析用户活动的 Model Context Protocol (MCP) 服务。可用时，匿名浏览会使用 Reddit 的公开 RSS 源。搜索、评论、用户分析和完整指标需要经批准的 Reddit API 访问权限。1.2.0 版新增了可选的发帖和评论功能，并设有每个进程的上限和依赖客户端的确认流程。参见发帖。

🎬 实际演示

Claude 查看 Reddit 对 Dune Part Three 预告片的反应，以及 AirPods Max 2 是否值得 549 美元

Claude 分析 r/cscareerquestions 和 r/india 中关于 H-1B 签证变更的实时情绪

目录

• Reddit MCP Buddy 有何不同？
• 快速开始
• 它能做什么？
• 可用工具
• 身份验证
• 发帖（v1.2.0）
• 安装选项
  • 全局安装
  • 从源代码安装
  • 使用 Docker
  • Claude Desktop 扩展
• 与其他工具的比较
• 故障排除
• 开发
• 支持
• 相关资源

Reddit MCP Buddy 有何不同？

• 🚀 匿名浏览 - 可用时，通过公开 RSS 源浏览 subreddit；其他实时数据工具需要经批准的 API 访问权限
• ✍️ 选择启用发帖（v1.2.0） - 创建帖子和评论，具有依赖客户端的确认流程、每个进程的上限和重复内容抑制
• ⚡ 本地速率限制 - 配置的上限为每分钟 10/60/100 个请求；Reddit 也会应用自己的限制
• 🎯 干净的数据 - 没有虚假的“情绪分析”或捏造的指标
• 🧠 针对大模型优化 - 专为 Claude 等 AI 助手打造
• 📦 TypeScript - 完全类型化、可靠且易于维护
• ✅ 速率限制测试 - 用于验证服务本地身份验证级别的工具

快速开始（30 秒）

面向 Claude Desktop - 桌面扩展（最简单！）

1. 下载：reddit-mcp-buddy.mcpb
2. 安装：打开下载的文件
3. 完成！ Reddit 工具现在已可在 Claude 中使用

面向 Claude Desktop - NPM 方法（备选）

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "reddit": {
      "command": "npx",
      "args": ["-y", "reddit-mcp-buddy"]
    }
  }
}

面向 Claude Code

运行此命令以添加 MCP 服务（用户范围）：

claude mcp add --transport stdio reddit-mcp-buddy -s user -- npx -y reddit-mcp-buddy

面向其他 MCP 客户端

使用 NPM 方法：npx -y reddit-mcp-buddy

它能做什么？

让你的 AI 助手：

• 📊 “Reddit 上最近有什么热门内容？” - 浏览 r/all 中的热门帖子
• 🔍 “搜索关于 AI 的讨论” - 搜索所有子版块
• 💬 “获取这篇 Reddit 帖子的评论” - 获取帖子及其完整评论串
• 👤 “分析用户 spez” - 获取用户历史记录、karma 和活动情况
• 📚 “解释 Reddit karma” - 了解 Reddit 术语
• ✍️ “把这篇内容发到 r/test” - 起草内容、检查子版块规则，并在你确认后提交（需主动启用，见发帖）

可用工具

browse_subreddit

使用排序选项浏览任意子版块的帖子。

- Subreddit:
  - "all" - entire Reddit frontpage
  - "popular" - trending across Reddit
  - Any specific subreddit (e.g., "technology", "programming", "science")
- Sort by: hot, new, top, rising, controversial
- Time range: hour, day, week, month, year, all (for top/controversial sort)
- Include subreddit info: Optional flag for subreddit metadata (requires credentials)

没有凭据？ 结果来自 Reddit 公共 RSS 源（data_source: "rss"）：score、num_comments、upvote_ratio 和 nsfw 会返回 null，且无法应用 include_nsfw 过滤条件。添加凭据（身份验证）即可通过 API 获取完整数据。

search_reddit

搜索整个 Reddit 或指定子版块。

- Query: Your search terms
- Filter by: subreddit, author, time, flair
- Sort by: relevance, hot, top, new, comments

get_post_details

获取帖子及其所有评论。

- Input:
  - Reddit URL (supports multiple formats), OR
  - Post ID alone (will auto-detect subreddit, 2 API calls), OR
  - Post ID + subreddit (most efficient, 1 API call)
- Supported URL formats:
  - reddit.com, www.reddit.com
  - old.reddit.com, new.reddit.com
  - np.reddit.com (No Participation links)
  - m.reddit.com (mobile links)
  - redd.it short URLs
  - URLs with query params (?utm_source=...) or fragments (#comment)
- Options: comment sorting, depth, link extraction

user_analysis

分析 Reddit 用户的个人资料。

- Username: Any Reddit user
- Returns: karma, posts, comments, active subreddits

reddit_explain

获取 Reddit 术语的解释。

- Terms: karma, cake day, AMA, ELI5, etc.

写入工具（需主动启用）

只有启用发帖后，才会显示 create_post、add_comment 和 subreddit_rules；只读安装中只会显示上述五个工具。详见发帖（v1.2.0）。

身份验证（可选）

搜索、帖子详情、用户分析和完整指标需要获批应用及使用场景对应的 Reddit API 凭据。

Reddit API 审批

Reddit 的负责任构建者政策要求使用其 API 前必须获得明确批准。创建应用并不保证能访问 API。Reddit 建议开发者优先使用 Devvit；对于 Devvit 不支持的使用场景，请使用 Reddit API 访问申请表。

如果你已经获得批准，请使用下方的应用凭据。本项目无法代为申请批准或保证审批时间，也不提供共享 API 密钥或第三方 OAuth 服务。

没有凭据时，browse_subreddit 可以使用公共 RSS 源，reddit_explain 则可离线运行。RSS 可能会被屏蔽或限流，且不提供互动指标或 NSFW 标记。它无法启用搜索、帖子详情或用户分析，也不能代替 API 审批。

设置步骤

1. 为你的应用和使用场景申请 Reddit API 审批，使用上方的链接。
2. 打开 https://www.reddit.com/prefs/apps 并选择获批的应用。如果 Reddit 要求你创建应用，请按其说明操作。
3. 填写表单：
   • 名称：例如，“mcp-buddy”。Reddit 会拒绝名称中包含“reddit”的客户端。
   • 应用类型：使用 “script” 进行密码授权，或使用 “web app” 通过 OAuth 同意流程获取刷新令牌。仅应用模式支持这两种方式。
   • 说明：可选
   • 关于 URL：留空
   • 重定向 URI：你注册的 OAuth 回调地址，例如 http://localhost:8080。密码授权不会使用此地址。
4. 按 Reddit 的指示完成应用注册。如果无法创建应用，请通过 Reddit 的访问申请流程继续跟进。
5. 查找你的凭据：
   • 客户端 ID：应用名称和类型下方的字符串
   • 客户端密钥：密钥字符串
6. 更新你的 Claude Desktop 配置：

{
  "mcpServers": {
    "reddit": {
      "command": "npx",
      "args": ["-y", "reddit-mcp-buddy"],
      "env": {
        "REDDIT_CLIENT_ID": "your_client_id",
        "REDDIT_CLIENT_SECRET": "your_client_secret",
        "REDDIT_USERNAME": "your_username",
        "REDDIT_PASSWORD": "your_password"
      }
    }
  }
}

采用 OAuth 授权的 Web 应用

经批准的 Web 应用无需 Reddit 密码即可验证用户身份。使用已注册的重定向 URI、由回调验证的随机 state 值，以及 duration=permanent，完成 Reddit 的授权码流程以获取刷新令牌。只读工具需要申请 identity、read 和 history 权限范围；Reddit 在其 API 参考中列出了各端点所需的权限范围。

在服务的环境中设置以下变量：

{
  "REDDIT_CLIENT_ID": "your_client_id",
  "REDDIT_CLIENT_SECRET": "your_client_secret",
  "REDDIT_REFRESH_TOKEN": "your_refresh_token"
}

使用刷新令牌时，请勿设置 REDDIT_PASSWORD。同时设置两者会导致服务在启动时拒绝运行。服务会按需将刷新令牌换取访问令牌，且不会将环境凭据写入 auth.json。不会使用从该文件加载的刷新令牌；请通过环境配置此模式。

请像保护密码一样保护刷新令牌。将其保存在版本控制之外，不再需要时，请在 Reddit 应用偏好设置中撤销访问权限。OAuth 授权不会授予 Reddit API 审批，也不会扩大获批的使用范围。

三层身份验证系统

Reddit MCP Buddy 执行以下本地上限。这些并非 Reddit API 配额，也不代表有保证的吞吐量：

模式	本地上限	所需凭据	适用场景
匿名	10 req/min*	无	测试、轻度使用
仅应用	60 req/min	客户端 ID + Secret	日常浏览
已验证身份	100 req/min	客户端 ID + Secret，以及刷新令牌或用户名/密码	重度使用、自动化

*服务端上限。匿名请求通过 Reddit 的未登录 RSS 源提供，该源会实施更严格的单 IP 限流（通常每 25-60 秒仅允许一次未缓存请求）。15 分钟缓存和自动重试可以缓解大部分影响，但持续进行匿名浏览时，实际速度会低于 10 req/min。

工作原理：

• 匿名模式：默认模式，无需设置。仅 browse_subreddit（以及离线工具 reddit_explain）可用：Reddit 会阻止未登录状态下的 JSON API 请求，因此浏览结果来自 Reddit 的公开 RSS 源（data_source: "rss"），互动指标和 NSFW 标记均为 null。其余工具需要凭据。
• 仅应用模式：使用 OAuth2 客户端凭据授权（脚本应用和 Web 应用均适用）
• 已验证身份模式：针对获授权的 Web 应用使用 OAuth2 刷新令牌身份验证，或针对脚本应用使用密码授权

重要说明：

• 客户端凭据会选择仅应用模式；刷新令牌或用户名/密码会选择用户身份验证。
• 刷新令牌携带授权时授予的权限范围。缺少权限范围可能导致个别工具无法使用。
• 用户身份验证会改变此服务的本地上限，但不会提高 Reddit 提供的配额。

发帖（v1.2.0）

从 v1.2.0 起，服务可以代表你发帖。提供三个工具，均需主动选择启用：

• create_post - 向一个 subreddit 提交文本帖或链接帖。会检查机械规则（标题限制、是否必须设置 flair、是否允许链接帖或文本帖），并支持使用 validate_only: true 进行试运行。是否需要确认取决于客户端的功能，如下文所述。
• add_comment - 对帖子发表评论，或回复特定评论（通过 ID 或 URL），并采用相同的确认流程。
• subreddit_rules - 只读工具。通过一次缓存调用获取 subreddit 的规则、发帖要求、功能标记和 flair 选项，便于在提交前完善草稿。

建议的工作流：先调用 subreddit_rules，然后使用 validate_only: true 调用 create_post，与用户一起检查完整草稿和选项，最后提交完全相同的请求内容。

启用发帖

在现有凭据旁添加 REDDIT_BUDDY_WRITE：

{
  "mcpServers": {
    "reddit": {
      "command": "npx",
      "args": ["-y", "reddit-mcp-buddy"],
      "env": {
        "REDDIT_CLIENT_ID": "your_client_id",
        "REDDIT_CLIENT_SECRET": "your_client_secret",
        "REDDIT_USERNAME": "your_username",
        "REDDIT_PASSWORD": "your_password",
        "REDDIT_BUDDY_WRITE": "true"
      }
    }
  }
}

Claude Desktop 扩展用户：改为在扩展设置中打开 启用发帖工具 开关。该开关会映射到同一个 REDDIT_BUDDY_WRITE 变量。

或者，将 REDDIT_PASSWORD 替换为上述 Web 应用授权流程获取的 REDDIT_REFRESH_TOKEN。发帖需要已授予 identity、read、submit 和 flair 权限范围。如果还使用 user_analysis，请添加 history。使用刷新令牌时，REDDIT_USERNAME 为可选项；如果提供，该值必须与 Reddit 返回的账户一致。

凭据必须来自环境变量（或会转换为环境变量的扩展配置字段）。交互式 --auth 文件设置不会启用发帖功能。启动时，服务会通过 Reddit 验证账户并检查已授予的权限范围。如果缺少任何要求，服务会记录原因，并保持发帖工具禁用。

通俗来说，安全模型如下

发帖会使用你的账户。服务会强制执行注册、速率限制和重复内容检查；是否需要人工批准也取决于客户端：

• 默认关闭。 未设置 REDDIT_BUDDY_WRITE 时，写入工具不会注册：只读安装与之前完全相同，仍只有 5 个工具，且不会额外占用上下文。
• 仅限 stdio。 HTTP 传输没有身份验证，因此写入工具不会在该传输方式下注册。你设备或网络上的任何进程都无法将 HTTP 端点变成发帖代理。
• 确认方式取决于客户端。 支持 MCP elicitation 的客户端会显示确认提示，其中包含目标、账户、内容预览、完整内容长度和发帖选项。必须明确接受才能继续。预览可能会被截断，因此请先在客户端中检查完整草稿。不支持 elicitation 时，服务要求先进行预览或成功的试运行，然后在 15 分钟内提交完全相同的载荷。服务无法验证是否有人工批准了这次重复操作：是否批准取决于客户端的工具提示，以及模型是否遵循指令。请仅在你信任其批准机制的客户端中启用发帖。
• 无法提高的每小时上限。 服务强制执行每小时最多发 5 篇帖子、30 条评论，且两次写入之间至少间隔 15 秒。环境变量可以收紧这些限制，但不能放宽。需要坦诚说明的是：这些限制由服务进程执行（重启会重置每小时计数，并行会话各自拥有独立上限，而且该开源代码的分支可以移除这些限制）。设置这些限制是为了让随意滥用得不偿失，而不是阻止蓄意操作的人。
• 抑制重复内容。 在 15 分钟内重试完全相同的提交时，服务会返回原帖，而不是重复发帖；即使是为同一 subreddit 重新起草的相同内容也一样。允许将相同内容发到不同的 subreddit，但会发出警告并指出较早发布的帖子。
• 提交后验证。 Reddit 有时会先返回“成功”，但帖子几秒后就被 AutoModerator 移除。提交后，服务会重新检查，并在发生这种情况时报告 status: "filtered" 并附上警告，而不是告诉你帖子已上线。
• 醒目的日志记录。 每次获准的写入都会记录到 stderr，其中包含操作类型、目标（已知时为 subreddit）和执行用户。

启用前请了解其中的权衡

Reddit 的密码授权会返回具有完整账户权限范围的令牌。OAuth 刷新令牌则携带授权时授予的权限。这些权限适用于整个账户，而不仅仅是某个 subreddit。关闭发帖时，服务使用凭据进行读取；启用发帖后，服务便可以提交帖子和评论。请勿将密码和刷新令牌纳入版本控制，也不要将其存放在共享设备上。

另外请注意：除了上述限制外，Reddit 还会根据账户年龄和 karma 对账户级发帖频率进行限制。如果 Reddit 提示“请在 N 分钟后重试”，服务会显示等待时间，而不会不断重试。

隐私与数据处理

Reddit MCP Buddy 的设计注重隐私和透明度。以下是数据的处理方式：

数据收集

• Reddit API 数据：服务通过 Reddit 官方 API 获取公开的 Reddit 内容（帖子、评论、用户个人资料）
• 不跟踪：我们不会收集、存储或传输任何分析、遥测或使用数据
• 无第三方：所有数据都直接在你的计算机、Reddit API 和 AI 助手之间流动

本地存储

• 身份验证凭据（可选）：
  • 使用 --auth CLI 设置时，凭据存储在本地的 ~/.reddit-mcp-buddy/auth.json 中
  • 密码绝不会写入磁盘——仅在内存中用于 OAuth 令牌交换
  • 环境变量（推荐用于 Claude Desktop）不会由此服务持久化
• 缓存数据：
  • Reddit API 响应会临时缓存在内存中，以提升性能
  • 缓存大小上限为 50MB
  • 服务停止时会清除所有缓存数据
  • 可通过 REDDIT_BUDDY_NO_CACHE=true 禁用

数据传输

• 仅限 Reddit API：你的凭据只会发送到 Reddit 官方 OAuth 端点（https://oauth.reddit.com 和 https://www.reddit.com）
• 无外部服务：不会向任何其他外部服务、分析平台或第三方发送数据
• 本地处理：所有数据处理都在你的计算机上本地进行

安全说明

• 默认只读：发布内容需要明确选择启用。启用前，请查看依赖客户端的确认流程。
• 凭据安全：
  • OAuth 令牌会自动刷新并保存在内存中；只有通过 --auth CLI 设置时，令牌才会同时缓存在 ~/.reddit-mcp-buddy/auth.json 中（文件权限为 600）
  • 客户端密钥被视为敏感信息，绝不会记录到日志中
  • 为获得最高安全性，请在 Claude Desktop 配置中使用环境变量
• 开源：完整源代码可在 https://github.com/karanb192/reddit-mcp-buddy 获取，供安全审计

GDPR 与隐私合规

• 不收集个人数据：除 Reddit API 身份验证所需的信息外，我们不会收集或处理任何个人数据
• 用户控制权：所有凭据均由你掌控，你可以随时删除 ~/.reddit-mcp-buddy/auth.json
• 删除权：只需删除身份验证文件或卸载服务，即可移除所有本地数据

有疑问或顾虑？

如果你对隐私有任何疑问或顾虑，请在 GitHub 上提交问题。

测试与开发

测试速率限制

Reddit MCP Buddy 包含全面的测试工具，可验证身份验证是否正常工作：

# Clone the repository first
git clone https://github.com/karanb192/reddit-mcp-buddy.git
cd reddit-mcp-buddy
npm install

# Test with your current environment settings
npm run test:rate-limit

# Test specific authentication modes
npm run test:rate-limit:anon    # Test anonymous mode (10 rpm)
npm run test:rate-limit:app     # Test app-only mode (60 rpm)
npm run test:rate-limit:auth    # Test authenticated mode (100 rpm)

速率限制测试器将：

• 启动本地服务实例
• 快速发送 API 请求以测试速率限制
• 显示实时进度条
• 确认你使用的身份验证级别
• 准确显示何时触发速率限制

交互式身份验证设置（仅用于本地测试）

对于本地开发和测试，你可以交互式地设置身份验证：

npx -y reddit-mcp-buddy --auth

系统会提示你输入 Reddit 应用凭据，并将其保存在本地。注意：此方式不适用于 Claude Desktop——请改为在 Claude 配置中使用环境变量。

私有测试版发帖测试

构建检出目录，然后打印拟议的测试内容，不发送任何请求：

npm run build
REDDIT_TEST_SUBREDDIT=your_private_sub node tests/live-write.mjs

实时运行需要已获批准的应用、REDDIT_CLIENT_ID 和 REDDIT_CLIENT_SECRET，以及 REDDIT_REFRESH_TOKEN 或脚本应用所需的 REDDIT_USERNAME/REDDIT_PASSWORD 组合。该账号必须是私有测试子版块的版主。OAuth 验证需要全部六个范围：identity、read、submit、flair，以及用于恢复的 history 和用于清理的 edit。测试框架会在连接任何发帖客户端前检查这些条件。请将凭据保存在仓库之外。在支持 --env-file 的 Node 版本中，可以通过本地环境文件提供这些凭据：

RUN_WRITE_TESTS=1 REDDIT_TEST_SUBREDDIT=your_private_sub \
  node --env-file=/path/to/private.env tests/live-write.mjs --run

此命令会执行实际写入。它会启动真正的 stdio MCP 连接，拒绝一条发帖请求，接受一条测试帖，并测试评论预览，随后由不支持征询的客户端提交相同内容。测试框架会自动提供确认响应；运行此命令即表示授权执行这些测试操作。它会创建一条帖子和一条评论，验证其内容，然后尝试删除两者，即使发生故障也会继续尝试。

唯一标记和任何清理失败都会打印出来，供手动检查。如果响应丢失，系统会搜索测试用户最新发布的帖子和评论；如果结果无法确定或删除未经验证，运行就会失败。如果进程被终止或 Reddit 无法访问，则无法保证完成清理。普通单元测试使用离线 API 固定数据，常规集成运行则会跳过发帖，除非明确启用。

使用 HTTP 模式测试

要在终端中直接测试服务：

# Run in HTTP mode on port 3000
npx -y reddit-mcp-buddy --http

# Or with custom port
REDDIT_BUDDY_PORT=8080 npx -y reddit-mcp-buddy --http

**注意：**默认情况下，服务以 stdio 模式运行（供 Claude Desktop 使用）。使用 --http 标志可通过 Postman MCP 或直接 API 调用进行测试。

安装选项

全局安装

npm install -g reddit-mcp-buddy
reddit-buddy --http  # For testing

从源代码安装

git clone https://github.com/karanb192/reddit-mcp-buddy.git
cd reddit-mcp-buddy
npm install
npm run build
npm link

使用 Docker

Docker 镜像和 CI 工作流使用 Node.js 26。要构建并运行镜像：

git clone https://github.com/karanb192/reddit-mcp-buddy.git
cd reddit-mcp-buddy
docker build --pull -t reddit-mcp-buddy .
docker run -it reddit-mcp-buddy

安装 Docker、curl 和 jq 后，运行容器冒烟测试：

bash tests/test-docker.sh reddit-mcp-buddy

该测试会检查容器健康状况、MCP 初始化、工具发现和关闭过程，无需 Reddit 凭据。

Claude Desktop 扩展

如需在 Claude Desktop 中一键安装，请下载预构建的扩展：

📦 下载 reddit-mcp-buddy.mcpb

**安装：**只需打开下载的 .mcpb 文件，Claude Desktop 就会自动安装扩展，随后即可使用 Reddit 工具。

从源代码构建（可选）

如果你希望自行构建扩展：

git clone https://github.com/karanb192/reddit-mcp-buddy.git
cd reddit-mcp-buddy
./scripts/build-mcpb.sh

注意：大多数用户应使用快速开始中所示的标准 npm 安装方式。

与其他工具的比较

特性	Reddit MCP Buddy	其他 MCP 工具
匿名访问	RSS 浏览；其他数据工具需要经批准的 API 访问权限	因服务而异
语言	TypeScript/Node.js	Python（大多数）
工具数量	5 个读取工具 + 3 个选择启用的写入工具	8-10 个（存在冗余）
虚假指标	✅ 仅真实数据	❌“情绪评分”
搜索	✅ 完整搜索	有限或不支持
缓存	✅ 智能缓存	通常没有
针对大模型优化	✅ 参数清晰	选项令人困惑
速率限制测试	✅ 内置工具	❌ 不提供验证

速率限制

模式	每分钟请求数	缓存 TTL	所需设置
匿名	10	15 分钟	无
仅应用	60	5 分钟	客户端 ID + 密钥
已认证	100	5 分钟	所有凭据

缓存 TTL 适用于子版块列表。在所有模式下，帖子详情（10 分钟）、搜索结果（10 分钟）和用户个人资料（15 分钟）均使用固定 TTL。匿名模式的吞吐量还会受到 Reddit 自身基于 IP 的 RSS 限流影响；对于未缓存的请求，其限制比每分钟 10 次更严格。

为什么选择 Reddit MCP Buddy？

其他方案的不足：

• ❌ 虚假指标 —— 所谓的“情感分数”其实只是关键词计数
• ❌ 设置复杂 —— 一开始就要求 API 密钥
• ❌ 响应臃肿 —— 返回 Reddit 原始 API 中 100 多个字段
• ❌ 与大模型集成不佳 —— 参数令人困惑，描述含糊不清

我们的优势：

• ✅ 只提供真实数据 —— 数据不是来自 Reddit API，我们就不会编造
• ✅ 响应简洁 —— 只包含重要字段
• ✅ 参数清晰 —— 大模型能准确理解需要发送什么
• ✅ 快速且带缓存 —— 条件允许时可即时响应

示例

你的 AI 现在可以回答：

“今天关于 GPT-4 的热门帖子有哪些？”

→ search_reddit with query="GPT-4", time="day", sort="top"

“告诉我科技领域有哪些热门趋势”

→ browse_subreddit with subreddit="technology", sort="hot"

“大家对这篇文章怎么看？”

→ search_reddit with the article URL to find discussions

“分析用户 DeepFuckingValue”

→ user_analysis with username="DeepFuckingValue"

“获取这篇 Reddit 帖子的评论”

→ get_post_details with url="https://reddit.com/r/..."

“整个 Reddit 上有哪些热门趋势？”

→ browse_subreddit with subreddit="all", sort="hot"

故障排除

常见问题

“无法创建应用”或“需要 API 审批”

• 按照 Reddit 的审批流程操作；本项目无法审批应用，也无法解除 Reddit 的限制
• 仅将凭据用于 Reddit 已批准的应用和使用场景

“无法达到每分钟 100 次请求”

• 10/60/100 档位是此服务的本地上限，并不代表 Reddit 保证提供相应的吞吐量
• 遵守 Reddit 的速率限制响应；添加账户凭据不会提高 Reddit 授予的配额
• 运行 npm run test:rate-limit:app 或 npm run test:rate-limit:auth，检查对应的本地模式（需要克隆仓库）

“找不到命令”错误

# Ensure npm is installed
node --version
npm --version

# Try the full global-bin path
$(npm prefix -g)/bin/reddit-mcp-buddy

浏览正常，但搜索 / 评论 / 用户分析失败

• 不提供凭据时，只有 browse_subreddit（通过 Reddit 的公开 RSS Feed 提供，不含评分或评论数）和离线工具 reddit_explain 可用
• 匿名浏览也可能触发 Reddit 自身的 RSS 速率限制（HTTP 429）；服务会自动重试，但持续受到限流仍可能导致失败
• 解决方法：添加 Reddit 凭据（请参阅身份验证）

速率限制错误

• 本地上限：未进行身份验证时每分钟 10 次请求，使用应用凭据时每分钟 60 次，完成完整身份验证时每分钟 100 次
• Reddit 对 API 和 RSS 分别实施限制；服务会重试暂时性故障，但持续受到限流仍可能导致失败
• 降低请求频率，并遵守 Reddit 的速率限制响应
• 如果错误提示 Retry in Ns，请等待相应时长后再重试。对于上游要求等待较长时间的情况，服务会立即返回，而不会一直等待到客户端请求超时。

未显示写入工具

• 以下条件必须全部满足：REDDIT_BUDDY_WRITE=true，通过环境变量提供客户端凭据以及刷新令牌或用户名 / 密码，使用 stdio 传输，用户身份已验证，并已授予 identity/read/submit/flair 作用域
• 启动日志（stderr）会明确指出未满足的条件
• 使用 --auth 文件的设置无法写入：密码不会保存，因此重启后会退回到仅使用应用令牌。请将凭据移至 MCP 客户端配置的 env 块中
• HTTP 模式按设计不会注册写入工具（HTTP 端点不提供身份验证）

“找不到版块”

• 检查拼写（不区分大小写）
• 某些版块可能设为私密或已隔离
• 请改用 “all” 或 “popular”

连接问题

• Reddit 可能出现故障（请查看 https://www.redditstatus.com）
• 防火墙阻止了请求
• 尝试重启 MCP 服务

环境变量

身份验证变量

变量	说明	必填	速率限制
REDDIT_CLIENT_ID	Reddit 应用客户端 ID	否	本地上限：60 req/min（需提供密钥）
REDDIT_CLIENT_SECRET	Reddit 应用密钥	否	本地上限：60 req/min（需提供 ID）
REDDIT_USERNAME	Reddit 账户用户名	否	本地上限：100 req/min（需提供全部 4 项）
REDDIT_PASSWORD	Reddit 账户密码	否	本地上限：100 req/min（需提供全部 4 项）
REDDIT_REFRESH_TOKEN	OAuth 刷新令牌；不要设置密码	否	提供客户端 ID 和密钥时，本地上限为 100 req/min
REDDIT_USER_AGENT	自定义用户代理字符串（配置凭据后生效）	否	-

服务配置

变量	说明	默认值
REDDIT_BUDDY_HTTP	以 HTTP 服务而非 stdio 模式运行	false
REDDIT_BUDDY_PORT	HTTP 服务端口（当 HTTP=true 时）	3000
REDDIT_BUDDY_HOST	HTTP 服务绑定的接口	127.0.0.1
REDDIT_BUDDY_ALLOWED_ORIGINS	允许调用 HTTP 端点的浏览器来源列表，以逗号分隔	无
REDDIT_BUDDY_ALLOWED_HOSTS	Host 标头中接受的 host:port 值列表，以逗号分隔（防止 DNS 重绑定）	绑定到 localhost 时为回环地址
REDDIT_BUDDY_NO_CACHE	禁用缓存（始终获取最新内容）	false

发帖（v1.2.0）

变量	说明	默认值
REDDIT_BUDDY_WRITE	注册发帖工具；需要环境变量中的用户凭据、已验证的身份和权限范围，以及 stdio	false
REDDIT_BUDDY_MAX_POSTS_PER_HOUR	每小时发帖数；仅接受 1 到 4 之间的值（0 和无效值将被忽略）	5
REDDIT_BUDDY_MAX_COMMENTS_PER_HOUR	每小时评论数；仅接受 1 到 29 之间的值（0 和无效值将被忽略）	30
REDDIT_BUDDY_MIN_WRITE_INTERVAL_S	两次写入之间的秒数；仅接受大于 15 的值	15

这三个速率下限变量只能收紧内置上限。故意如此：将其设置得比默认值宽松不会产生任何效果，而且 0 不代表“暂停发帖”，而是恢复为默认上限。

HTTP 模式没有身份验证。 它绑定到 localhost，因此只有你的计算机可以访问，并且会拒绝回环地址范围之外的 Host 标头。将 REDDIT_BUDDY_HOST=0.0.0.0 会使整个网络都能访问它——仅在可信网络中这样做（例如在 Docker 中，因为 Docker 会有意设置此值）。绑定到非回环地址时，默认关闭 Host 检查，因为客户端可能会使用容器 IP 或服务名称访问；可设置 REDDIT_BUDDY_ALLOWED_HOSTS 来限制访问。除非来源列在 REDDIT_BUDDY_ALLOWED_ORIGINS 中，否则浏览器请求会被拒绝；Postman 等非浏览器客户端不受影响。

HTTP 和 HTTPS 代理

在 22.x 系列的 Node 22.21.0+，或 Node 24 及更高版本上，请在启动服务前启用 Node 内置的代理支持。项目的 Node 26 Docker 镜像支持此功能。请先检查 node --version：不受支持的版本可能会忽略这些设置并直接连接。Node 目前将此功能标记为仍在积极开发中。

{
  "mcpServers": {
    "reddit": {
      "command": "npx",
      "args": ["-y", "reddit-mcp-buddy"],
      "env": {
        "NODE_USE_ENV_PROXY": "1",
        "HTTP_PROXY": "http://proxy.example.com:8080",
        "HTTPS_PROXY": "http://proxy.example.com:8080",
        "NO_PROXY": "localhost,127.0.0.1"
      }
    }
  }
}

HTTP_PROXY 用于转发 HTTP 请求；HTTPS_PROXY 用于转发 HTTPS 请求，包括 Reddit API 和 RSS 调用。NO_PROXY 用于排除匹配的主机。通过在 shell 中导出这些变量以供 CLI 使用，或通过 Docker 的 -e 选项传入。请在启动前将它们设置在进程环境中；服务不会自动加载项目的 .env 文件。

在 Docker 内部，localhost 指的是容器。在 Docker Desktop 上，使用 host.docker.internal 连接运行在主机上的代理。

代理身份验证信息可以包含在代理 URL 中，例如 http://username:[email protected]:8080。请将该值视为凭据，并在共享的日志和配置中将其隐去。对于使用私有证书颁发机构的网络，请使用 NODE_EXTRA_CA_CERTS 指定组织的 PEM 证书文件，而不要禁用 TLS 验证。

请参阅 Node 的代理和证书配置指南。代理支持用于转发网络流量；它不会授予 Reddit API 使用许可，也不会绕过 Reddit 的访问规则。

技术详情

智能缓存系统

Reddit MCP Buddy 包含智能缓存，可提升性能并减少 API 调用：

• 内存安全：上限为 50MB，不会影响系统性能
• 按内容设置 TTL：帖子详情（10 分钟）、用户资料（15 分钟）、搜索结果（10 分钟）；subreddit 列表使用模式默认值（匿名时为 15 分钟，使用凭据时为 5 分钟）
• LRU 淘汰：接近上限时自动移除最少使用的数据
• 命中跟踪：根据实际使用模式优化缓存

这样既能加快响应速度，又能让 Reddit API 调用保持在速率限制范围内，同时只占用极少的系统资源。

开发

# Install dependencies
npm install

# Run in development
npm run dev

# Build
npm run build

# Run tests
npm test                     # Unit tests
npm run test:integration     # Integration tests
npm run test:all             # All tests

# Test rate limits
npm run test:rate-limit       # Test with current environment
npm run test:rate-limit:anon  # Test anonymous mode (10 rpm)
npm run test:rate-limit:app   # Test app-only mode (60 rpm)
npm run test:rate-limit:auth  # Test authenticated mode (100 rpm)

# Lint
npm run lint

# Type check
npm run typecheck

要求

• Node.js >= 18.0.0
• npm 或 yarn
• TypeScript 5.5+

贡献

欢迎提交 PR！请参阅 CONTRIBUTING.md 了解指南。

我们坚持简单：

• 不做虚假分析
• 代码简洁且类型明确
• 文档清晰
• 响应迅速

支持

• 🐛 报告错误
• 💡 请求功能
• ⭐ 在 GitHub 上点 Star

🔗 相关资源

MCP 官方资源

• MCP Registry - MCP 服务官方注册表
• MCP Specification - Model Context Protocol 官方规范
• MCP TypeScript SDK - 用于构建此服务的 SDK
• MCP Servers Repository - MCP 服务官方实现集合
• Awesome MCP Servers - 社区整理的 MCP 服务列表

查找此服务

• MCP Registry API Link - 此服务的直接 API 查询
• MCP Registry Search - 搜索“reddit”以查找所有版本
• NPM Package - 通过 npm/npx 安装
• GitHub Repository - 源代码和问题

通过 API 查看所有版本

# Get all versions of reddit-mcp-buddy from the registry
curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=reddit-mcp-buddy" | jq

# Get just names, version numbers, and latest flag
curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=reddit-mcp-buddy" | \
  jq '.servers[] | {name: .server.name, version: .server.version, isLatest: ._meta."io.modelcontextprotocol.registry/official".isLatest}'

许可证

MIT - 随你使用！

---

为 MCP 社区倾心打造。没有风险投资，没有跟踪，只有一个出色的 MCP 服务。

由 Karan Bansal（ArmorCode 的 AI 负责人）打造。我在 karanbansal.in/blog 撰写有关 Claude Code、MCP 和生产级 Agentic AI 的文章。