freshrss

FreshRSS MCP Server provides a bridge between your FreshRSS instance and AI-powered assistants via the Model Context Protocol. The server exposes tooling to list feeds, inspect feed groups, fetch unread items, retrieve specific feed items, and mark items as read or unread. This enables an assistant to browse subscriptions, fetch content from particular feeds, and perform state changes (read/unread) through a standard MCP interface. Typical use cases include streaming unread items for summarization, querying content by feed, and marking items as read after processing in an AI workflow.

To use the tools, you’ll interact with the following MCP commands exposed by the server: list_feeds (list all feed subscriptions), get_feed_groups (retrieve feed groups), get_unread (fetch unread items), get_feed_items (retrieve items from a specific feed), mark_item_read/mark_item_unread (toggle read state for individual items), mark_feed_read (mark an entire feed as read), and get_items (fetch specific items by IDs). You’ll provide the appropriate MCP commands and arguments through the MCP client, and the server will proxy requests to FreshRSS using the Fever API credentials you configure via environment variables. Ensure your FreshRSS instance is accessible from the server host and that API access is enabled.

Prerequisites:

• Node.js (recommended LTS version) installed on your machine or server
• A FreshRSS instance with API access enabled
• Access credentials for FreshRSS (URL, username, password)

Install steps:

1. Clone or download the MCP server repository for FreshRSS.
2. Install dependencies:

npm install

3. Build the TypeScript project (produces build/index.js):

npm run build

4. (Optional) Enable development with auto-rebuild:

npm run watch

5. Configure environment variables for FreshRSS access (see Environment Variables in the project). You can set them in your deployment environment or via a dedicated config file. Example:

export FRESHRSS_API_URL="https://your-freshrss-instance.com"
export FRESHRSS_USERNAME="your-username"
export FRESHRSS_PASSWORD="your-password"

6. Run the server using Node.js (the MCP config will point to build/index.js):

node /path/to/freshrss-server/build/index.js

Notes:

• If you run inside containerized environments, pass the environment variables through your container orchestration tooling (Docker, Kubernetes, etc.).
• Ensure the server process has network access to your FreshRSS instance.
• For debugging, refer to the MCP Inspector tool recommended in the project documentation.

Environment variables are sensitive; avoid hard-coding credentials in source. Use a secrets manager or environment injection mechanism in your deployment environment. Common issues include network connectivity to FreshRSS, incorrect API URL or credentials, and insufficient permissions on the FreshRSS user. If you encounter authentication errors, double-check the FreshRSS user has API access enabled and that the Fever API is reachable from the MCP server host. When configuring for Claude Desktop or Cline MCP integrations, ensure the same environment variables are available to the client or wrapper that loads the MCP server configuration.