ni-c/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.
is resolved against the colour scheme of the page showing it, so GitHub
picks the variant that matches its own theme toggle. npm strips and
when it sanitises the README and keeps the , which is why that
fallback brings its own dark card instead of relying on a media query. -->
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
| Variable | Required | Description |
| ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| FRESHRSS_URL | yes | Root URL of the instance, e.g. https://rss.example.com. The API path /api/greader.php is appended automatically. |
| FRESHRSS_USER | yes | FreshRSS user name. |
| FRESHRSS_API_PASSWORD | yes | The **API password** from the profile page, not the web login password. |
| FRESHRSS_READ_ONLY | no | 1, true or yes registers only the read tools. |
| FRESHRSS_INSECURE_TLS | no | true accepts self-signed certificates for this connection only. |
| FRESHRSS_ALLOW_TOOLS | no | Comma-separated tool names, list_* prefixes, or essential for a curated preset |
| FRESHRSS_DENY_TOOLS | no | Same syntax; removed from whatever FRESHRSS_ALLOW_TOOLS left |
| ELICITATION | no | false replaces the approval dialog with the two-call token. **Not prefixed.** |
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.
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 Desktop
Codex
Docker
The image is published for linux/amd64 and linux/arm64 with an SBOM and build