freshrss-mcp

一个用于 FreshRSS（自托管的 RSS 和 Atom 订阅聚合器）的 模型上下文协议 服务器。

它使用 FreshRSS 在 /api/greader.php 暴露的 Google Reader 兼容 API 进行通信，并将该 API 的古怪之处隐藏在助手可以实际使用的工具参数后面：数字化的订阅源 ID、类别和标签名称、ISO 日期和十进制文章 ID，而不是 user/-/state/com.google/… 流标识符和十六进制项目标签。

📖 完整文档：freshrss-mcp.ni-c.de

要求

• Node.js 22 或更新版本

• 一个 FreshRSS 实例（针对 1.29 开发），需满足：

  • 已启用 API：设置 → 认证 → “允许 API 访问”

  • 已为用户设置 API 密码：设置 → 个人资料 → API 管理。 这是与 Web 登录密码不同的独立密码。

Related MCP server: Conduit

配置

服务器启动时不带凭据，因此其工具保持可列出状态；但每次调用都会失败并显示这些设置说明。

Claude Code

claude mcp add freshrss -- npx -y @ni-c/freshrss-mcp

Claude Desktop

{
  "mcpServers": {
    "freshrss": {
      "command": "npx",
      "args": ["-y", "@ni-c/freshrss-mcp"],
      "env": {
        "FRESHRSS_URL": "https://rss.example.com",
        "FRESHRSS_USER": "alice",
        "FRESHRSS_API_PASSWORD": "…"
      }
    }
  }
}

Codex

[mcp_servers.freshrss]
command = "npx"
args = ["-y", "@ni-c/freshrss-mcp"]
env = { FRESHRSS_URL = "https://rss.example.com", FRESHRSS_USER = "alice", FRESHRSS_API_PASSWORD = "…" }

工具

读取

写入

当 FRESHRSS_READ_ONLY=true 时不注册。

无搜索

FreshRSS 不通过其 API 提供全文搜索——Google Reader 端点仅按流、已读状态和日期过滤。因此 list_articles 没有查询参数；使用 feed_id/category 和 since/until 缩小结果范围，并自行过滤返回的文章。

安全性

• 文章文本是不可信的输入。 此服务器从 FreshRSS 返回的所有内容均由互联网上的第三方编写，因此携带文章文本、标题或订阅源名称的响应可能会将密码或私人订阅源的密码泄露到对话记录中。

• subscribe_feed 拒绝内部目标。 FreshRSS 在服务器端获取 URL，这使得该工具成为可从文章文本中访问的 SSRF 原语。回环地址和链路本地地址（包括云元数据端点）被拒绝。私有 LAN 地址仍然允许，因为自托管设置合法地订阅自己网络上的订阅源。

• import_opml 拒绝 <!DOCTYPE>。 此过程中不解析 XML，但文档会传递给 FreshRSS，其中文档类型声明是实体扩展和外部实体攻击的载体。OPML 永远不需要它。

• FRESHRSS_READ_ONLY=true 根本不会注册写入工具，而不是在调用时拒绝它们。

哪些工具受确认令牌保护：mark_all_as_read、unsubscribe_feed、delete_category_or_label 和 import_opml。mark_articles 故意不受保护——调用者明确指定最多 100 篇文章，并且每个字段都可以重置——但它被声明为破坏性操作，因此客户端仍可能提示确认。

容器

docker run --rm -i \
  -e FRESHRSS_URL=https://rss.example.com \
  -e FRESHRSS_USER=alice \
  -e FRESHRSS_API_PASSWORD=... \
  ghcr.io/ni-c/freshrss-mcp:latest

该镜像发布为 linux/amd64 和 linux/arm64，附带 SBOM 和构建来源。它以非特权 node 用户身份运行，并且不携带 npm，因此其中只有 Node、运行时依赖项和 dist/。

开发

npm install
npm run lint && npm run build && npm test
npm run test:coverage

请参阅 CONTRIBUTING.md 了解用于开发的临时 FreshRSS 实例。完整文档位于 freshrss-mcp.ni-c.de。

发布

1. 将 CHANGELOG.md 中的 [Unreleased] 条目移到新版本下，并更新 package.json 中的 version。

2. 运行 npm run lint && npm run build && npm run test:coverage。

3. 提交，然后打标签：git tag -s vX.Y.Z -m vX.Y.Z && git push origin main vX.Y.Z。

标签会触发 release.yml，它会验证标签是否与 package.json 匹配，通过 可信发布 发布到 npm（无需令牌，附带来源），从 CHANGELOG 部分创建 GitHub 发布，并将条目发布到 MCP 注册表。如果只有注册表步骤失败，请在 main 上修复并手动重新运行 mcp-registry.yml——切勿重新运行带标签的作业，因为那会检出旧树。

许可证

MIT