FreshRSS MCP Server for AI Agents

An MCP server that wraps the FreshRSS Google Reader API, exposing feed management, safe full-article extraction, and YouTube transcript retrieval as tools for AI agents. It uses Streamable HTTP transport and works with Codex and other MCP clients.

Token-optimized: returns only essential fields with configurable summary truncation, achieving ~90% reduction vs raw RSS XML payloads.

This repository is derived from ChrisLAS/freshrss-mcp, created by Chris Fisher and released under the MIT License. The original copyright and license are preserved. See NOTICE for the upstream attribution and a summary of the added functionality.

Added agent-reading capabilities

• fetch_full_article: extracts readable text from public article pages with redirect, size, content-type, and SSRF protections.

• get_youtube_transcript: retrieves existing YouTube captions through Supadata, optionally permits paid AI transcription, and caches results locally.

• Docker deployment for small always-on hosts such as Raspberry Pi.

• Tests for URL validation, secret masking, article extraction, transcript normalization, and tool error boundaries.

Related MCP server: agent-reach-mcp

NixOS Installation

The flake exports a NixOS module that runs the server as a hardened systemd service.

1. Add the flake input

In your host's flake.nix:

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

Pass it through to your NixOS configuration:

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

2. Configure the service

In your host config (e.g. 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
};

The password file must use systemd EnvironmentFile format:

FRESHRSS_PASSWORD=your-api-password-here

3. Rebuild

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

The service runs as a sandboxed DynamicUser with hardened security settings.

OpenClaw Gateway Setup

Register the FreshRSS MCP server in the openclaw-mcp-bridge plugin inside ~/.openclaw/openclaw.json. Add a server entry to the existing servers array:

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

Then restart the gateway: openclaw gateway restart

Tools will appear with the freshrss_ prefix, e.g. freshrss_list_feeds, freshrss_get_unread_articles.

For AI Agents: Setup & Installation Guide

This section is written for agentic LLM sessions that need to deploy, configure, or extend this server.

Quick Start (non-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

Docker

docker build -t freshrss-mcp .
docker run --rm -p 127.0.0.1:8000:8000 \
  -e FRESHRSS_URL="https://freshrss.example.com" \
  -e FRESHRSS_USERNAME="youruser" \
  -e FRESHRSS_PASSWORD="your-api-password" \
  -e MCP_SERVER_HOST="0.0.0.0" \
  -v freshrss-mcp-cache:/cache \
  freshrss-mcp

Add SUPADATA_API_KEY only if you want the YouTube transcript tool. Never commit API keys or FreshRSS credentials to the repository.

Quick Start (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

On NixOS, the Nix devshell sets UV_PYTHON_DOWNLOADS=never and UV_PYTHON automatically to avoid dynamically linked binary issues.

Verify the Server

# 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

Environment Variables

Available Tools

Architecture Notes

• Transport: Streamable HTTP (POST /mcp), not stdio. The OpenClaw openclaw-mcp-bridge plugin discovers tools via HTTP.

• Auth: Lazy authentication — the FreshRSS client authenticates on the first API call, not at startup.

• Error handling: Every tool catches all exceptions and returns "Error: ..." strings. MCP protocol never sees uncaught exceptions.

• Config: pydantic-settings BaseSettings with SecretStr for the password. Validation happens at startup.

• Dependencies: aiohttp, fastmcp, httpx, pydantic-settings, and trafilatura. No version pins.

• Secrets: FreshRSS and Supadata credentials are read from environment variables and represented with SecretStr.

• Tests: Unit tests cover config, client, tools, models, article extraction, and transcript handling. Run with uv run pytest -v.

Project Structure

src/freshrss_mcp/
  server.py    — FastMCP entry point, signal handlers, streamable-http transport
  tools.py     — 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
  article_fetcher.py — public-only HTTP fetch and readable-text extraction
  youtube_transcript.py — Supadata transcript client and persistent cache
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
  test_article_fetcher.py — URL safety, redirect, and extraction behavior
  test_youtube_transcript.py — YouTube URL parsing and transcript normalization

Known Limitations

• Client-side search: FreshRSS API lacks server-side search; search_articles fetches articles then filters locally.

• No pagination: Article fetches use a single limit parameter without cursor-based pagination.

• No real-time updates: The server is request-driven; no push/webhook mechanism for new articles.

License

MIT. The upstream copyright notice remains in LICENSE; modification details are in NOTICE.