freshrss-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@freshrss-mcp show me my unread articles from the last day"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
truncatedalways reported.Article ids are FreshRSS's real ids and are stable across restarts.
FreshRSS setup
In FreshRSS go to Settings > Authentication and enable Allow API access.
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.
The API endpoint is
<your FreshRSS URL>/api/greader.php. Use the final URL (for example thehttps://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.0Prefer 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-mcpConfiguration
Environment variables only.
Variable | Required | Description |
| yes | Base URL of FreshRSS, e.g. |
| yes | FreshRSS username |
| yes | The API password (not the login password) |
| for SSE | Bearer token clients must send over SSE, at least 32 characters ( |
| no |
|
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_TOKENThe 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 |
| Feeds with id, title, URL, categories and unread count |
| Categories with unread counts |
| Total, per-feed and per-category unread |
|
|
| One article by id, text up to |
| Case-insensitive search over title and body; reports |
| All subscriptions as OPML |
Write (not registered in read-only mode):
Tool | Purpose |
| By article id (max 100 per call) |
| By article id (max 100 per call) |
| Subscribe to a feed URL, optionally with title and category |
| Rename a feed and/or move it to a category ( |
| Rename a category |
Destructive (not registered in read-only mode; refuse unless confirm=true):
Tool | Purpose |
| Unsubscribe from a feed and delete its articles |
| Delete a category |
| Import subscriptions from OPML (max 1 MB) |
| 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; setFRESHRSS_READ_ONLY=trueif 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=truestops 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_opmlrejects OPML that sets per-feed network options (CURLOPT_*) or dynamic OPML sources, which FreshRSS would otherwise honour for API imports.freshrss_subscribeonly acceptshttp(s)URLs, but FreshRSS makes the request. Keep FreshRSS's own SSRF guard on: do not setINTERNAL_HOST_ALLOWLISTon 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_articlesfetches pages and filters them. It scans at mostmax_scanarticles (default 200, max 500), newest first, and says so inscannedandtruncated.Local feed URLs. FreshRSS refuses to subscribe to feeds on private addresses unless its
INTERNAL_HOST_ALLOWLISTis 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 pytestUnit 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 toolsfreshrss_delete_categoryBDestructive
Delete a category. Requires confirm=true.
Inputs: name (required), confirm. Returns: object
freshrss_edit_feedAIdempotent
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_opmlARead-onlyIdempotent
Export all subscriptions as OPML.
Inputs: no named parameters. Returns: object
freshrss_get_articleARead-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_countsCRead-onlyIdempotent
Unread totals: overall, per feed and per category.
Inputs: no named parameters. Returns: object
freshrss_import_opmlADestructive
Import subscriptions from OPML text (at most 1 MB). Requires confirm=true.
Inputs: opml (required), confirm. Returns: object
freshrss_list_articlesARead-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_categoriesARead-onlyIdempotent
List categories (folders) with their unread counts.
Inputs: no named parameters. Returns: result
freshrss_list_feedsARead-onlyIdempotent
List subscribed feeds with id, title, url, categories and unread count.
Inputs: no named parameters. Returns: result
freshrss_mark_all_readADestructive
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_readBIdempotent
Mark articles read by id (at most 100).
Inputs: ids (required). Returns: object
freshrss_mark_unreadBIdempotent
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_articlesARead-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_starAIdempotent
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_unstarAIdempotent
Unstar articles by id (at most 100).
Inputs: ids (required). Returns: object
freshrss_unsubscribeADestructive
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
Scored across 18 tools
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.
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.
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.
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
Related MCP Connectors
RSS & Atom feed manager with full-text search, AI curation, and remote MCP endpoint.
Managed cloud RSS and Atom feed reader with a remote Model Context Protocol (MCP) endpoint. Zero server setup required — enables AI agents like Claude to instantly subscribe to feeds, search full-text articles, extract readable content, and access curated AI editions ("Your Newspaper") over secure streamable HTTP.
Read, search and organize the RSS feeds you follow in Feeder. Tool calls need Feeder Plus.
Fetch any RSS/Atom feed as clean JSON or extract article text from any URL. Built for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables interaction with RSS readers that support the FreshRSS API through natural language. Allows users to manage and query their RSS feeds and articles via LLM conversations.7MIT
- FlicenseNot gradedqualityDmaintenanceEnables interaction with FreshRSS RSS feed readers through the Google Reader compatible API. Supports feed management, article reading/searching, and marking articles as read or starred.-
- AlicenseBqualityDmaintenanceEnables interaction with FreshRSS instances through the Google Reader API. Supports managing articles, feeds, folders, labels, and OPML import/export for RSS feed aggregation through natural language.2734 npm2MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with FreshRSS feeds via the Fever API, allowing listing feeds, fetching unread items, marking items as read/unread, and managing feed subscriptions.86 npm10MIT