playbooks

home / mcp / freshrss mcp server

FreshRSS MCP Server

Provides a FreshRSS MCP server exposing Google Reader API endpoints to browse feeds, read articles, and manage subscriptions.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "jeromewoody-freshrss-mcp": {
      "url": "https://your-freshrss-server.com",
      "headers": {
        "FRESHRSS_EMAIL": "[email protected]",
        "FRESHRSS_PASSWORD": "your-password"
      }
    }
  }
}

You can run a dedicated MCP server that connects FreshRSS to a Google Reader–style API. It lets you browse feeds, read articles, and manage subscriptions through a protocol your MCP client understands, with authentication handled at startup for secure access.

How to use

Start the MCP server and provide your FreshRSS credentials once. After it initializes, you can use an MCP client to list subscriptions, fetch articles, search your library, and mark items as read or starred. Use stream IDs to target feeds, categories, or reading lists, and rely on the server to translate your requests into FreshRSS API calls.

How to install

Prerequisites: Python 3.7 or newer and a working Python environment with access to install dependencies.

Install the required Python packages.

pip install -r requirements.txt

Run the MCP server with your FreshRSS credentials from the command line.

# Using command line arguments
python freshrss_mcp_server.py --url https://your-freshrss-server.com --email [email protected] --password your-password

Or provide credentials via environment variables and start the server with the URL only.

export FRESHRSS_EMAIL="[email protected]"
export FRESHRSS_PASSWORD="your-password"
python freshrss_mcp_server.py --url https://your-freshrss-server.com

Configuration and usage notes

Authentication is performed during startup. The server exposes endpoints compatible with the Google Reader API, including user info, subscriptions, stream contents, tagging, and unread counts. Use the provided stream IDs to access all articles, starred items, reads, or specific feeds and categories.

Typical command-line startup options are shown above. If you need to adjust credentials, you can switch between command-line arguments and environment variables as shown.

API compatibility and endpoints

This server implements the Google Reader API endpoints supported by FreshRSS, enabling authentication at startup and access to user info, subscriptions, streams, edits/tags, unread counts, and categories.

Available tools

get_user_info

Retrieve information about the authenticated user.

list_subscriptions

List all RSS feed subscriptions for the authenticated user.

add_subscription

Add a new RSS feed subscription for the user.

list_categories

List all categories or tags with unread counts.

get_articles

Fetch articles from feeds, categories, or the reading list.

search_articles

Search articles by keywords across the subscribed feeds.

get_starred_articles

Retrieve all articles marked as starred.

get_unread_counts

Obtain unread article counts per feed or category.

mark_article_read

Mark a specific article as read.

mark_article_starred

Star or unstar an article.

mark_all_as_read

Mark all articles in a stream as read.