Skip to main content
Glama
freshrss-mcp

freshrss-mcp

by hrsather

freshrss-mcp

An MCP server that lets an AI assistant read, triage and manage feeds in your own FreshRSS instance. It talks to FreshRSS through its Google Reader compatible API, so it works with any FreshRSS server that has the API enabled.

  • 18 tools: read articles, search, mark read/starred, subscribe, organise categories, OPML.

  • Destructive tools refuse to run unless called with confirm=true.

  • Read-only mode that does not register any write tool.

  • stdio (default) or SSE with a required bearer token.

  • Article text is plain text, cut to a size you control, with truncated always reported.

  • Article ids are FreshRSS's real ids and are stable across restarts.

FreshRSS setup

  1. In FreshRSS go to Settings > Authentication and enable Allow API access.

  2. Go to Settings > Profile and set an API password. This is separate from your login password and can be changed at any time to revoke access.

  3. The API endpoint is <your FreshRSS URL>/api/greader.php. Use the final URL (for example the https:// one): the server does not follow redirects.

Tested against FreshRSS 1.30.4. The minimum supported version is not documented upstream.

Related MCP server: FreshRSS MCP Server

Install

Container (linux/amd64 and linux/arm64):

docker run --rm -i \
  --read-only --cap-drop ALL --security-opt no-new-privileges \
  -e FRESHRSS_URL=https://rss.example.com \
  -e FRESHRSS_USERNAME=me \
  -v "$PWD/api-password:/run/secrets/api-password:ro" \
  -e FRESHRSS_API_PASSWORD_FILE=/run/secrets/api-password \
  ghcr.io/hrsather/freshrss-mcp:0.1.0

Prefer the _FILE variants for the password and bearer token: a value passed with -e shows up in docker inspect and in the host's process list. The container runs as uid 10001, so the file must be readable by it (for example chmod 644 api-password).

From source with uv:

uvx --from git+https://github.com/hrsather/freshrss-mcp freshrss-mcp

Configuration

Environment variables only.

Variable

Required

Description

FRESHRSS_URL

yes

Base URL of FreshRSS, e.g. https://rss.example.com

FRESHRSS_USERNAME

yes

FreshRSS username

FRESHRSS_API_PASSWORD

yes

The API password (not the login password)

MCP_BEARER_TOKEN

for SSE

Bearer token clients must send over SSE, at least 32 characters (openssl rand -hex 32)

FRESHRSS_READ_ONLY

no

true removes every write and destructive tool

FRESHRSS_URL, FRESHRSS_USERNAME, FRESHRSS_API_PASSWORD and MCP_BEARER_TOKEN also accept a _FILE variant (for example FRESHRSS_API_PASSWORD_FILE=/run/secrets/freshrss) that reads the value from a file.

Run

freshrss-mcp                                            # stdio
freshrss-mcp --transport sse --host 0.0.0.0 --port 8080 # SSE, needs MCP_BEARER_TOKEN

The SSE endpoint is /sse; send Authorization: Bearer <MCP_BEARER_TOKEN>.

Client configuration (stdio):

{
  "mcpServers": {
    "freshrss": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
               "-e", "FRESHRSS_URL", "-e", "FRESHRSS_USERNAME", "-e", "FRESHRSS_API_PASSWORD",
               "ghcr.io/hrsather/freshrss-mcp:0.1.0"],
      "env": {
        "FRESHRSS_URL": "https://rss.example.com",
        "FRESHRSS_USERNAME": "me",
        "FRESHRSS_API_PASSWORD": "..."
      }
    }
  }
}

Client configuration (SSE, for a server running elsewhere):

{
  "mcpServers": {
    "freshrss": {
      "type": "sse",
      "url": "https://freshrss-mcp.example.com/sse",
      "headers": { "Authorization": "Bearer <MCP_BEARER_TOKEN>" }
    }
  }
}

Tools

All tools return JSON and carry MCP read-only / destructive hints. Errors are plain, actionable strings.

Read:

Tool

Purpose

freshrss_list_feeds

Feeds with id, title, URL, categories and unread count

freshrss_list_categories

Categories with unread counts

freshrss_get_unread_counts

Total, per-feed and per-category unread

freshrss_list_articles

stream (unread, all, starred, feed, category), target, limit (max 50), cursor, since, order, unread_only, max_chars

freshrss_get_article

One article by id, text up to max_chars

freshrss_search_articles

Case-insensitive search over title and body; reports scanned and truncated

freshrss_export_opml

All subscriptions as OPML

Write (not registered in read-only mode):

Tool

Purpose

freshrss_mark_read, freshrss_mark_unread

By article id (max 100 per call)

freshrss_star, freshrss_unstar

By article id (max 100 per call)

freshrss_subscribe

Subscribe to a feed URL, optionally with title and category

freshrss_edit_feed

Rename a feed and/or move it to a category ("" is the default category)

freshrss_rename_category

Rename a category

Destructive (not registered in read-only mode; refuse unless confirm=true):

Tool

Purpose

freshrss_unsubscribe

Unsubscribe from a feed and delete its articles

freshrss_delete_category

Delete a category

freshrss_import_opml

Import subscriptions from OPML (max 1 MB)

freshrss_mark_all_read

Mark every article in a stream read

Feed ids look like feed/12; article ids look like tag:google.com,2005:reader/item/0006.... Pass next_cursor from one freshrss_list_articles result as cursor to get the next page.

Security

  • The API password and bearer token are never logged or returned in tool output or errors.

  • SSE requires a bearer token (compared in constant time). Do not expose the SSE port publicly without TLS in front of it.

  • Destructive tools need an explicit confirm=true; set FRESHRSS_READ_ONLY=true if the assistant should never change anything.

  • The container runs as a non-root user and holds no state, so it works with --read-only --cap-drop ALL --security-opt no-new-privileges.

  • Feed content is untrusted. Text from feeds is plain text with control and bidi characters removed, but it can still contain instructions aimed at the model. confirm=true stops accidents, not a determined prompt injection: if the assistant reads feeds you do not trust, run in read-only mode or only expose the tools you need.

  • freshrss_import_opml rejects OPML that sets per-feed network options (CURLOPT_*) or dynamic OPML sources, which FreshRSS would otherwise honour for API imports.

  • freshrss_subscribe only accepts http(s) URLs, but FreshRSS makes the request. Keep FreshRSS's own SSRF guard on: do not set INTERNAL_HOST_ALLOWLIST on an instance this server can reach unless you need private-address feeds.

Report vulnerabilities as described in SECURITY.md.

Known limits

  • Search is client-side. FreshRSS has no server-side search over the Google Reader API, so freshrss_search_articles fetches pages and filters them. It scans at most max_scan articles (default 200, max 500), newest first, and says so in scanned and truncated.

  • Local feed URLs. FreshRSS refuses to subscribe to feeds on private addresses unless its INTERNAL_HOST_ALLOWLIST is set; this surfaces as an HTTP 400 error.

  • Only the Google Reader API is supported (no Fever API) and only one FreshRSS user per server.

  • Greader implementations differ between FreshRSS versions; only 1.30.4 is tested.

Development

uv sync
uv run ruff check && uv run ruff format --check && uv run mypy && uv run pytest

Unit and protocol tests run against an in-memory fake of the API. Integration tests run against a real FreshRSS and are skipped unless FRESHRSS_TEST_URL is set; see CONTRIBUTING.md.

License

MIT

Available Tools

18 tools
freshrss_delete_categoryB
Destructive

Delete a category. Requires confirm=true.

Inputs: name (required), confirm. Returns: object

freshrss_edit_feedA
Idempotent

Rename a feed and/or move it to category (an empty string moves it to the default category). feed is the feed id, e.g. feed/12.

Inputs: feed (required), title, category. Returns: object

freshrss_export_opmlA
Read-onlyIdempotent

Export all subscriptions as OPML.

Inputs: no named parameters. Returns: object

freshrss_get_articleA
Read-onlyIdempotent

Get one article by its id, with plain text up to max_chars (see truncated).

Inputs: id (required), max_chars. Returns: object

freshrss_get_unread_countsC
Read-onlyIdempotent

Unread totals: overall, per feed and per category.

Inputs: no named parameters. Returns: object

freshrss_import_opmlA
Destructive

Import subscriptions from OPML text (at most 1 MB). Requires confirm=true.

Inputs: opml (required), confirm. Returns: object

freshrss_list_articlesA
Read-onlyIdempotent

List articles. stream is unread, all, starred, feed or category; target is the feed id (e.g. feed/12) or category name for the last two. limit is at most 50; pass next_cursor from the previous result as cursor for the next page. since is an ISO 8601 date or datetime; order is newest or oldest. unread_only filters feed, category and starred streams. Text is plain, cut to max_chars (see truncated); use freshrss_get_article for more.

Inputs: limit, order, since, cursor, +4 more. Returns: object

freshrss_list_categoriesA
Read-onlyIdempotent

List categories (folders) with their unread counts.

Inputs: no named parameters. Returns: result

freshrss_list_feedsA
Read-onlyIdempotent

List subscribed feeds with id, title, url, categories and unread count.

Inputs: no named parameters. Returns: result

freshrss_mark_all_readA
Destructive

Mark every article in a stream (all, starred, feed or category; target as in freshrss_list_articles) as read. Requires confirm=true.

Inputs: stream, target, confirm. Returns: object

freshrss_mark_readB
Idempotent

Mark articles read by id (at most 100).

Inputs: ids (required). Returns: object

freshrss_mark_unreadB
Idempotent

Mark articles unread by id (at most 100).

Inputs: ids (required). Returns: object

freshrss_rename_categoryC

Rename a category.

Inputs: name (required), new_name (required). Returns: object

freshrss_search_articlesA
Read-onlyIdempotent

Case-insensitive text search over title and body. FreshRSS has no server-side search, so this scans the newest max_scan articles (at most 500) of the stream; the result reports scanned and truncated (true when older articles were not checked).

Inputs: query (required), limit, stream, target, +3 more. Returns: object

freshrss_starA
Idempotent

Star articles by id (at most 100).

Inputs: ids (required). Returns: object

freshrss_subscribeB

Subscribe to the feed at url, optionally with a title and a category (created if missing).

Inputs: url (required), title, category. Returns: object

freshrss_unstarA
Idempotent

Unstar articles by id (at most 100).

Inputs: ids (required). Returns: object

freshrss_unsubscribeA
Destructive

Unsubscribe from a feed, deleting its articles. Requires confirm=true.

Inputs: feed (required), confirm. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 18 tools

    Disambiguation4/5

    Each tool maps to a distinct resource/action pair (feeds, categories, articles, OPML, read/star state), and descriptions clarify parameters and stream semantics. Minor overlap exists: freshrss_get_unread_counts partially duplicates data from list_feeds/list_categories, and mark_all_read overlaps conceptually with mark_read, but boundaries remain clear.

    Naming Consistency5/5

    All tools share the freshrss_ prefix with a consistent snake_case verb_noun pattern (list_feeds, get_article, mark_read, delete_category). Even the paired state toggles (mark_read/mark_unread, star/unstar) follow a predictable symmetry.

    Tool Count4/5

    18 tools is slightly on the heavy side but each covers a genuine operation across feeds, categories, articles and OPML. Nothing appears redundant enough to remove, though the count sits at the upper edge of a comfortable set.

    Completeness4/5

    Strong lifecycle coverage: feed subscribe/edit/unsubscribe/list, category list/rename/delete, article read/search/mark/star, and bidirectional OPML. Gaps are minor — there is no standalone create_category (only implicit via subscribe) and no feed URL/refresh-settings update.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers