FreshRSS MCP Server

How to use

To connect with a MCP client, run the FreshRSS MCP server locally and point your client to the MCP endpoint you started. You can operate core FreshRSS features such as listing articles, filtering by read state, marking items as read or unread, starring articles, managing feeds and folders, and exporting/importing subscriptions. The server exposes a stable set of actions you can invoke from your MCP client, enabling you to automate common FreshRSS workflows without interacting with the FreshRSS web UI directly.

Typical usage patterns include listing unread articles, fetching starred items, subscribing to new feeds via quickadd, and organizing feeds into folders. You can also export or import OPML to transfer your subscriptions between instances. For convenience, Fever-style helpers return feed favicons and provide IDs for unread or starred articles, improving downstream automation.

How to install

Prerequisites: ensure you have Node.js 18+ installed on your system.

Install the MCP server globally with npm.

npm install -g @equaldepth/freshrss-mcp-server

Create a configuration that points to your FreshRSS instance and credentials. You will run the MCP server in a local environment and provide connection details via environment variables in your MCP client configuration blocks.

{
  "mcpServers": {
    "freshrss": {
      "command": "npx",
      "args": ["@equaldepth/freshrss-mcp-server"],
      "env": {
        "FRESHRSS_URL": "https://your-freshrss-instance.com",
        "FRESHRSS_USERNAME": "your-username",
        "FRESHRSS_API_PASSWORD": "your-api-password"
      }
    }
  }
}

If you use an editor or automation tool that supports multiple MCP configurations, you can mirror the same setup in another configuration block to run the server under a separate client or environment.

Start the MCP server by running the configuration in your environment. The server will expose an MCP endpoint for your client to connect and perform the available actions.

Examples and configuration snippets

Use one of the provided configuration blocks to set up the MCP server in your preferred environment. The blocks below show how to configure the FresRSS MCP server with a local npx runtime.

{
  "mcpServers": {
    "freshrss": {
      "command": "npx",
      "args": ["@equaldepth/freshrss-mcp-server"],
      "env": {
        "FRESHRSS_URL": "https://your-freshrss-instance.com",
        "FRESHRSS_USERNAME": "your-username",
        "FRESHRSS_API_PASSWORD": "your-api-password"
      }
    }
  }
}

Notes on usage

If you plan to run multiple MCP servers for different instances, replicate the config blocks with distinct environment settings. Ensure each server has its own unique name in the top-level mcpServers object to avoid conflicts.

Development

For development, you can run checks and build steps to ensure type safety and linting before starting the server.

npm run dev
npm run lint
npm run typecheck
npm run format
npm run build

Security and access

Securely manage your FreshRSS credentials. Store API passwords as secrets or environment variables in your deployment platform, and never hard-code them in source files. Use TLS (HTTPS) for all connections to your FreshRSS instance to protect credentials in transit.

Examples of actions available

The server exposes actions to manage content and subscriptions, including listing articles, marking them as read or unread, starring or unstarring, subscribing to feeds, editing feed details, and exporting/importing OPML.

Troubleshooting

If the MCP server fails to connect to FreshRSS, verify the URL, username, and API password. Ensure the FreshRSS API is enabled and that API access is permitted from the MCP host. Check network access and firewalls, and review the MCP server logs for connection errors.

License

MIT license.

Tooling and endpoints

The MCP server provides endpoints for articles, feeds, folders, labels, and stats. You can use client tools to list articles, read/unread them, subscribe to feeds, and export/import OPML.

list_articles

Retrieve articles with filters for unread, starred, or other states and specify ordering and count.

mark_as_read

Mark specified articles as read to update their read state.

mark_as_unread

Mark specified articles as unread to reset their read state.

star_articles

Mark selected articles as starred to flag them for quick access.

unstar_articles

Remove the starred flag from selected articles.

mark_all_as_read

Mark all articles as read in the current view or feed.

list_feeds

List subscribed feeds and their metadata.

subscribe

Add a new feed by URL, with an optional title and category.

unsubscribe

Remove a feed subscription.

edit_feed

Edit feed properties such as title or category.

export_opml

Export your subscriptions as an OPML file.

import_opml

Import subscriptions from an OPML file.

quickadd_feed

Quick-add a site URL and let FreshRSS discover the feed automatically.

list_folders

List all user folders.

list_labels

List all labels/tags used in subscriptions.

add_labels

Attach labels to feeds or articles.

remove_labels

Remove labels from feeds or articles.

rename_folder

Rename a folder.

rename_label

Rename a label.

delete_folder

Delete a folder.

delete_label

Delete a label.

get_stats

Retrieve usage statistics for the authenticated user.

get_user_info

Fetch basic information about the authenticated user.

list_favicons

List available favicons for feeds via Fever API.

get_feed_favicon

Get the favicon for a specific feed.

list_unread_article_ids

List IDs of unread articles.

list_starred_article_ids

List IDs of starred articles.