freshrss-mcp

An MCP server that puts a small, well-typed toolset in front of a FreshRSS instance, so an AI assistant (Claude, etc.) can read and manage your feeds: list subscriptions, browse unread/starred articles, read full content, mark read/unread, star, add feeds, and mark whole streams read.

It talks to FreshRSS over its built-in Google Reader-compatible API (/api/greader.php), so it works with any standard FreshRSS install — no plugins or schema changes required.

The server speaks MCP over streamable HTTP on a single port and gates the endpoint with a static bearer token. /healthz is open for liveness/readiness.

Tools

Tool	Description
whoami	Authenticated user + instance URL — a quick connectivity/credentials check.
list_feeds	Subscribed feeds with category and unread count.
list_categories	Categories/folders with total unread count.
list_articles	Articles (newest first), filterable by unread/starred/all, by feed or category, with an optional contains substring filter and pagination.
get_article	Full HTML content of a single article by id.
mark_read / mark_unread	Toggle read state for one or more article ids.
star / unstar	Toggle the star/favorite for one or more article ids.
mark_all_read	Mark an entire stream (all, a feed, or a category) read, optionally only items older than N seconds.
add_feed	Subscribe to a new feed URL, optionally filed under a category.

Article ids returned by list_articles/get_article are the values you pass back to the mutating tools.

Configuration

All configuration is via environment variables (see .env.example):

Variable	Required	Description
FRESHRSS_URL	yes	Base URL of your FreshRSS instance, without /api/... (e.g. https://rss.example.com).
FRESHRSS_USER	yes	FreshRSS username.
FRESHRSS_API_PASSWORD	yes	The per-user API password (see below) — not the web login password.
MCP_TOKEN	recommended	Bearer token clients must send. If unset, the MCP endpoint is unauthenticated — only acceptable for purely local use.
PORT	no	Listen port (default 8080).
FRESHRSS_TIMEOUT	no	Per-request timeout to FreshRSS, seconds (default 30).

Enabling the FreshRSS API

1. In FreshRSS, go to Settings → Authentication and enable "Allow API access" (the global toggle for the GReader/Fever APIs).
2. Go to Settings → Profile and set an API password. This is a dedicated password used only by API clients; it is separate from your login password. Put it in FRESHRSS_API_PASSWORD.

Running locally

cp .env.example .env        # then edit .env with your instance details
pip install -r requirements.txt
set -a && . ./.env && set +a
python server.py
# MCP endpoint:  http://localhost:8080/mcp
# Health check:  http://localhost:8080/healthz

Or with Docker:

docker build -t freshrss-mcp .
docker run --rm -p 8080:8080 --env-file .env freshrss-mcp

Connecting a client

Add it as a streamable-HTTP MCP server. With the Claude Code CLI:

claude mcp add --transport http freshrss https://your-host/mcp \
  --header "Authorization: Bearer $MCP_TOKEN"

Any MCP client that supports HTTP transports works the same way: point it at https://your-host/mcp and send Authorization: Bearer <MCP_TOKEN>.

Security notes

• No secrets live in this repo. Credentials are supplied only at runtime via environment variables. .env is gitignored; only .env.example (placeholders) is committed.
• Always set MCP_TOKEN for any networked deployment — without it the endpoint is open to anyone who can reach it.
• The server stores no data on disk; every call proxies to FreshRSS. The ClientLogin token is held only in memory and refreshed automatically on 401.
• Prefer giving the MCP its own FreshRSS user/API password so access can be revoked independently of your main account.

How it works

server.py is a single FastMCP streamable-HTTP app. A small GReader client handles ClientLogin auth (token cached in memory, auto-refreshed on 401) and the handful of GReader endpoints the tools need. A Starlette middleware enforces the bearer token on everything except /healthz.

License

MIT