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

Writing

Not registered when FRESHRSS_READ_ONLY=true.

Structured output

Every tool declares an outputSchema and answers with structuredContent alongside the text block, so a client can use the result without parsing prose:

{
  "untrusted": true,
  "source": "freshrss",
  "articles": [{ "id": "1234", "title": "…", "read": false, "starred": false }],
  "continuation": "1699999999",
  "notes": ["…"],
}

Every tool that reports feed content carries untrusted: true and source: "freshrss" as fields. This server has always said so in notes — prose in a list, which a client can read but not check — and the field is what makes it checkable. Eight tools are without it, because their answer is entirely this server's own words: ids it was given, a sentence built from the arguments, the account it authenticates as.

Six tools used to answer with a sentence ("Feed 9 deleted."); they now answer with the fields as well, and the sentence stays in the text block. export_opml returns {opml} rather than the document as the whole result: a schema whose root is a string is served to a 2025-era client rewritten as {result: …}, and truncated needs somewhere to live either way.

No search

FreshRSS does not offer full-text search over its API — the Google Reader endpoints filter by stream, read state and date only. list_articles therefore has no query parameter; narrow the result with feed_id/category and since/until and filter the returned articles yourself.

Not exposed, on purpose

No full-text search, because FreshRSS offers none over the Google Reader API: its endpoints filter by stream, read state and date only. Narrow with feed_id, category, since and until, then filter the returned articles yourself. The search in the FreshRSS web interface has no API endpoint behind it.

No raw HTML. Article bodies are converted to plain text and capped per article and per response, so one listing cannot bury everything else in the context.

Safety

• Article text is untrusted input. Everything this server returns from FreshRSS was written by a third party on the internet, so responses that carry article text, titles or feed names are explicitly marked as data, never as instructions.
• A person is asked, not just told. Where the client supports MCP elicitation, the five irreversible tools raise a real dialog that the model cannot answer on its behalf. A plain boolean could be set on the very first call, or be talked into it by text hidden in a feed. Where the client cannot show a dialog they fall back to a single-use token bound to the exact target, and say so rather than implying somebody approved. The messages deliberately never quote titles or names coming from the API. See Asking a person.
• Response budgets. FreshRSS returns up to 500 000 characters of HTML per article. Article text is converted to plain text, capped per article and against a per-response budget, and is opt-in in listings. The budget is charged for the markup that was read rather than for the text that came out, so it bounds the conversion work and not only the resulting context — markup that strips away to nothing is the expensive case, and it used to be free. The conversion itself is a single left-to-right scan, linear in the length of the article whatever the article contains.
• Credentials are read once, removed from process.env afterwards and never written to disk. Requests never follow redirects, which would resend the authorization header to another host, and relaxed TLS validation is scoped to this connection instead of the whole process.
• Feed URLs are redacted. FreshRSS stores HTTP-auth feeds as https://user:password@host/feed. The userinfo part is stripped before a feed URL reaches a tool result or the OPML export, so list_feeds cannot print the password of a paid or private feed into the transcript.
• subscribe_feed and import_opml refuse internal targets. FreshRSS fetches those URLs server-side, which makes both tools an SSRF primitive reachable from text inside an article. Loopback and link-local addresses — including cloud metadata endpoints — are rejected, for the feed URL and for every xmlUrl/htmlUrl in an OPML document. Addresses are compared numerically, so an IPv4-mapped IPv6 literal such as [::ffff:169.254.169.254] is caught too, and a hostname is resolved before it is accepted. An OPML document is read the way an XML parser reads it, and what reaches FreshRSS is the document as checked — so the URL that was inspected is the URL that gets fetched. Private LAN addresses stay allowed, because self-hosted setups legitimately subscribe to feeds on their own network.
• import_opml refuses a <!DOCTYPE>. No XML is parsed in this process, but the document is handed to FreshRSS, where a document type declaration is the carrier for entity-expansion and external-entity attacks. OPML never needs one.
• FRESHRSS_READ_ONLY=true does not register the write tools at all rather than refusing them at call time.

Which tools ask a person: mark_all_as_read, unsubscribe_feed, delete_category_or_label, import_opml — and mark_articles, but only when it is about to mark something read. Starring, unstarring and labelling can all be set back; which of those articles were unread cannot, and FreshRSS keeps no record of it.

Documentation

The full guide, tool reference and security notes live at freshrss-mcp.ni-c.de (source in docs/).

Development

npm install
npm run lint && npm run build && npm test
npm run test:coverage

See CONTRIBUTING.md for a throwaway FreshRSS to develop against. The full documentation lives at freshrss-mcp.ni-c.de.

Releasing

1. Move the [Unreleased] entries in CHANGELOG.md under the new version and bump version in package.json.
2. npm run lint && npm run build && npm run test:coverage.
3. Commit, then tag: git tag -s vX.Y.Z -m vX.Y.Z && git push origin main vX.Y.Z.

The tag triggers release.yml, which verifies the tag matches package.json, publishes to npm via Trusted Publishing with provenance (no token involved), creates the GitHub release from the CHANGELOG section, and publishes the entry to the MCP Registry. If only the registry step fails, fix it on main and re-run mcp-registry.yml by hand — never re-run the tagged job, which would check out the old tree.

Contributing

Issues, discussions and pull requests are welcome — see CONTRIBUTING.md. For vulnerabilities please use private reporting rather than a public issue; the policy is in SECURITY.md.

License

MIT © Willi Thiel