freshrss-mcp

A Model Context Protocol (MCP) server for FreshRSS, the self-hosted RSS and Atom feed aggregator.

Lets MCP clients like Claude Code, Claude Desktop or Codex work through your feeds: see what is unread, read the articles, mark them, and manage subscriptions and categories.

Sixteen tools is the ceiling, not the floor: FRESHRSS_ALLOW_TOOLS=essential registers a curated seven instead, and a model picks the right tool far more reliably from seven than from sixteen — see choosing which tools load.

It speaks the Google Reader compatible API that FreshRSS exposes at /api/greader.php, and hides that API's quirks behind tool arguments an assistant can actually use: numeric feed ids, category and label names, ISO dates and decimal article ids instead of user/-/state/com.google/… stream identifiers and hexadecimal item tags.

What makes it different

Sixteen tools, no stream ids. The Google Reader API speaks in stream identifiers and hexadecimal item tags. These tools take numeric feed ids, category and label names, ISO dates and decimal article ids, and hand back plain text instead of raw HTML.

Built for untrusted feeds. Every article was written by a stranger on the internet, so responses are marked as data, feed URLs are stripped of credentials, and article text is capped per article and per response. The five irreversible tools ask a person first, through MCP elicitation.

Requirements

• Node.js 22 or newer
• A FreshRSS instance (developed against 1.29) with
  • the API enabled: Settings → Authentication → "Allow API access"
  • an API password set for the user: Settings → Profile → API management. This is a separate password from the web login.

Configuration

The server starts without credentials so its tools stay listable; every call then fails with these setup instructions.

Choosing which tools load

FRESHRSS_ALLOW_TOOLS and FRESHRSS_DENY_TOOLS take comma-separated tool names; a trailing * matches a whole family. essential is a curated preset of seven: list_feeds, list_categories, get_unread_counts, list_articles, get_articles, mark_articles, mark_all_as_read.

FRESHRSS_ALLOW_TOOLS=essential
FRESHRSS_ALLOW_TOOLS=list_feeds,list_articles,mark_articles
FRESHRSS_DENY_TOOLS=delete_*

An entry that matches no tool aborts startup and names it, so a typo cannot silently hide a tool — an absent tool is not something anyone traces back to an environment variable. A filtered tool is never registered, so it is absent from tools/list and unknown to tools/call alike, exactly like a write tool under FRESHRSS_READ_ONLY.

If you run several of these servers at once, mcp-hub is the other answer — its /hub endpoint replaces every server's tools with six meta-tools.

Installation

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 = "…" }

Docker

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

The image is published for linux/amd64 and linux/arm64 with an SBOM and build provenance. It runs as the unprivileged node user and carries no npm, so the only thing in it is Node, the runtime dependencies and dist/.

Through mcp-hub

A client that cannot spawn a local process — ChatGPT connectors, Claude on the web, Cursor, LibreChat — reaches freshrss-mcp through mcp-hub: one container serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login behind a single password and long-lived tokens for the clients that cannot do OAuth. Its /hub endpoint puts every server behind six meta-tools, so one connector reaches all of them without N×tool schemas in the model's context, and it speaks both protocol revisions — a question this server asks travels through it to the person at the far end.

Its /config/mcp.json uses Claude Code's format, so the entry is the one you already have:

{
  "mcpServers": {
    "freshrss": {
      "command": "npx",
      "args": ["-y", "@ni-c/freshrss-mcp"],
      "env": { "FRESHRSS_ALLOW_TOOLS": "essential" },
      "denyTools": ["delete_*"]
    }
  }
}

allowTools and denyTools there are the hub's own per-server filter, which is not the same thing as *_ALLOW_TOOLS in env — the difference, and the mistake it invites, are in the client guide.

Tools

Reading