AI导哈

RSS订阅管理服务

一个封装FreshRSS Google Reader API的MCP服务器，为AI代理提供RSS订阅管理工具，支持流式HTTP传输并与OpenClaw网关集成。

  • by ChrisLAS
  • Python
  • 本地部署
  • 8 星标
  • 更新于
在 GitHub 查看 ChrisLAS/freshrss-mcp

使用说明

FreshRSS MCP服务器

一个MCP服务器，包装了FreshRSS谷歌阅读器API，将RSS提要管理作为人工智能代理的工具。用途 流式HTTP 通过传输与OpenClaw网关集成 openclaw-mcp-bridge 插件。

令牌优化：仅返回具有可配置摘要截断的基本字段，与原始RSS XML有效载荷相比，减少了约90%。

NixOS安装

flake导出一个NixOS模块，该模块将服务器作为强化的systemd服务运行。

1.添加薄片输入

在你的主人的 flake.nix:

inputs = {
  freshrss-mcp.url = "github:ChrisLAS/freshrss-mcp";
  freshrss-mcp.inputs.nixpkgs.follows = "nixpkgs";
};

将其传递到您的NixOS配置：

nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
  modules = [
    ./system.nix
    freshrss-mcp.nixosModules.default
  ];
};

2.配置服务

在您的主机配置中（例如。 system.nix):

services.freshrss-mcp-server = {
  enable = true;
  freshRssUrl = "https://freshrss.example.com";
  username = "youruser";
  passwordFile = "/home/youruser/.config/secrets/freshrss-mcp";
  port = 3005;
  host = "0.0.0.0";  # or "127.0.0.1" for loopback only
};

密码文件必须使用systemd EnvironmentFile格式：

FRESHRSS_PASSWORD=your-api-password-here

3.重建

sudo nixos-rebuild switch
systemctl status freshrss-mcp-server  # verify it's running

该服务作为具有强化安全设置的沙盒DynamicUser运行。

OpenClaw网关设置

在中注册FreshRSS MCP服务器 openclaw-mcp-bridge 插件内部 ~/.openclaw/openclaw.json。将服务器条目添加到现有条目中 servers 数组：

{
  "plugins": {
    "entries": {
      "openclaw-mcp-bridge": {
        "enabled": true,
        "config": {
          "servers": [
            {
              "name": "FreshRSS",
              "url": "http://127.0.0.1:3005",
              "prefix": "freshrss"
            }
          ]
        }
      }
    }
  }
}

然后重新启动网关： openclaw gateway restart

工具将与 freshrss_ 前缀，例如。 freshrss_list_feeds, freshrss_get_unread_articles.

AI代理：设置和安装指南

本节是为需要部署、配置或扩展此服务器的代理LLM会话编写的。

快速入门（非NixOS）

# Clone
git clone https://github.com/ChrisLAS/freshrss-mcp.git
cd freshrss-mcp

# Install deps (requires Python 3.12+ and uv)
uv sync

# Set required env vars
export FRESHRSS_URL="https://freshrss.example.com"
export FRESHRSS_USERNAME="youruser"
export FRESHRSS_PASSWORD="yourpass"

# Start server (binds to 127.0.0.1:8000/mcp by default)
uv run freshrss-mcp

# Override host/port
export MCP_SERVER_HOST="0.0.0.0"
export MCP_SERVER_PORT=3005
uv run freshrss-mcp

快速入门（NixOS）

# Enter dev shell (provides uv, python, ruff)
nix develop

# Install deps and run tests
uv sync
uv run pytest -v

# Start the server
export FRESHRSS_URL="https://freshrss.example.com"
export FRESHRSS_USERNAME="youruser"
export FRESHRSS_PASSWORD="yourpass"
uv run freshrss-mcp

在NixOS上，Nix devshell集 UV_PYTHON_DOWNLOADS=never 和 UV_PYTHON 自动避免动态链接二进制问题。

验证服务器

# List tools via JSON-RPC
curl -s http://127.0.0.1:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq .

# Call a tool
curl -s http://127.0.0.1:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_feeds","arguments":{}}}' | jq .

# MCP Inspector (interactive)
npx @modelcontextprotocol/inspector --url http://127.0.0.1:8000/mcp

环境变量

变量 必填 默认 描述
FRESHRSS_URL 是 -- FreshRSS实例URL
FRESHRSS_USERNAME 是 -- FreshRSS用户名
FRESHRSS_PASSWORD 是 - FreshRSS API密码
FRESHRSS_API_PATH 没有 /api/greader.php Google阅读器API路径
MCP_SERVER_HOST 没有 127.0.0.1 绑定地址
MCP_SERVER_PORT 没有 8000 绑定端口

可用工具

工具 描述 关键参数
get_unread_articles 使用筛选功能获取未读文章 limit, feed_ids, since_timestamp, max_summary_length
get_articles_by_feed 来自特定订阅源的文章 feed_id, limit, include_read
search_articles 标题/摘要中的客户端关键字搜索 query, limit, feed_ids
list_feeds 所有未读订阅源 --
get_feed_info 一个提要的详细信息 feed_id
get_feed_stats 所有订阅源的统计信息 --
mark_as_read 将文章批量标记为已读 article_ids
mark_as_unread 批量将文章标记为未读 article_ids
star_article 明星/最喜欢的文章 article_id
unstar_article 从文章中删除星号 article_id

架构说明

  • 运输：流式HTTP（POST /mcp)，而不是stdio。OpenClaw openclaw-mcp-bridge 插件通过HTTP发现工具。
  • 认证：惰性身份验证-FreshRSS客户端在第一个API调用时进行身份验证，而不是在启动时。
  • 错误处理：每个工具都会捕获所有异常和返回 "Error: ..." 串。MCP协议从不出现未捕获的异常。
  • 配置：媒染剂设置 BaseSettings 随着 SecretStr 对于密码。验证发生在启动时。
  • 依赖项: fastmcp, httpx, pydantic-settings。没有版本引脚。
  • 测试：67个单元测试，涵盖配置、客户端、工具和模型。与一起跑步 uv run pytest -v.

项目结构

src/freshrss_mcp/
  server.py    — FastMCP entry point, signal handlers, streamable-http transport
  tools.py     — 10 MCP tool definitions with error boundaries
  client.py    — Async FreshRSS Google Reader API client (httpx)
  config.py    — pydantic-settings config from env vars
  models.py    — Article and Feed dataclasses
tests/
  test_config.py   — Config validation, defaults, secret masking
  test_client.py   — Auth, feeds, articles, ID extraction
  test_tools.py    — Tool happy paths + error boundaries
  test_models.py   — Serialization, construction, edge cases

已知限制

  • 客户端搜索：FreshRSS API缺少服务器端搜索； search_articles 获取文章，然后在本地进行筛选。
  • 无分页：文章获取使用单个 limit 参数没有基于光标的分页。
  • 无实时更新：服务器是请求驱动的；新文章没有推送/webhook机制。

许可证

麻省理工学院

相关 MCP