FreshRSS MCP Server

An MCP server that wraps the FreshRSS Google Reader API, exposing RSS feed management as tools for AI agents. Uses Streamable HTTP transport for integration with the OpenClaw gateway via the openclaw-mcp-bridge plugin.

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

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

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: fastmcp, httpx, pydantic-settings. No version pins.
• Tests: 67 unit tests covering config, client, tools, and models. Run with uv run pytest -v.

Project Structure

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

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